1. 拡張タイプコードの範囲外エラー

シリアライズ処理中にExtension TypeCode is invalid例外が発生する場合、指定された拡張タイプコードが有効範囲外です。

var code = extensionHeader.TypeCode;
if (code is < 0 or > 127)
{
    throw new MessagePackSerializationException(
        $"Extension type code out of range: {code} (allowed: 0-127)");
}

修正手順：カスタム拡張機能で使用するタイプコードは0～127の範囲に制限し、プロトコル予約領域を回避してください。

2. バッファサイズ不一致エラー

構造体のシリアライズ時、Extension Length is invalidエラーが発生する場合はメモリ配置に不整合があります。

int requiredSize = Unsafe.SizeOf<DataStruct>();
if (header.PayloadLength != requiredSize)
{
    throw new MessagePackSerializationException(
        $"Buffer size mismatch: expected={requiredSize}, actual={header.PayloadLength}");
}

対処方法：UnsafeBlitFormatter実装時にsizeof(T)と実際のデータ長を厳密に照合してください。

3. 多次元配列の形式不正

2次元配列処理でInvalid T[,] format例外が発生する場合は、次元情報の整合性が失われています。

if (array.Rank != 2 || array.GetLength(0) * array.GetLength(1) != elementCount)
{
    throw new MessagePackSerializationException("Multi-dimensional array dimension mismatch");
}

解決策：ArrayFormatterの実装でGetLength()による次元検証を追加し、直列化形式と実データ構造を一致させてください。

4. Unity環境でのタイプコード不整合

UnityプロジェクトでInvalid typeCodeエラーが発生する場合、Blit互換フォーマッタの設定に問題があります。

if (!BlittableTypeMap.Contains(type))
{
    Debug.LogError($"Unsupported blittable type: {type.Name}");
    throw new InvalidOperationException("Type code validation failed");
}

対応策：Unity専用ビルドではUnityBlitResolverを使用し、非Blittable型を明示的に除外してください。

5. フォーマッタ未登録エラー

カスタム型のシリアライズ時にフォーマッタが検出されない場合は、解決機構の設定が不完全です。

修正ポイント：

• アセンブリ初期化時にMessagePackSerializer.DefaultOptionsにカスタムリゾルバを設定
• データ契約クラスに[Union]属性で明示的なバージョニングを指定
• コードジェネレータ出力が正しく参照されているか確認

6. バージョン間互換性問題

異なるバージョンのライブラリ間でデータ交換できない場合は、バイナリ形式の変更が原因です。

互換性確保方法：

• 全プロジェクトで同一メジャーバージョンを採用
• MessagePackSerializerOptionsでCompatibilityOptionsを指定
• スキーマ変更時は[Key]属性で固定インデックスを付与

7. LZ4圧縮処理エラー

圧縮データのデシリアライズで破損が発生する場合は、コーデック設定に不一致があります。

検証手順：

• 圧縮/解凍で同一のLZ4Codec.Levelを指定
• ネイティブライブラリMessagePack.LZ4の参照を確認
• 一時的にMessagePackCompression.Noneで動作検証

8. オブジェクト循環参照エラー

相互参照オブジェクトでスタックオーバーフローが発生する場合は、循環参照が検出されています。

回避策：

• 参照プロパティに[IgnoreDataMember]属性を付与
• カスタムフォーマッタで循環検出ロジックを実装
• 代わりに参照ID方式のシリアライズを採用

9. パフォーマンス最適化手法

高頻度シリアライズ処理でGC負荷が発生する場合は、メモリ管理を改善できます。

var buffer = ArrayPool<byte>.Shared.Rent(estimatedSize);
try
{
    // バッファ再利用によるシリアライズ
    serializer.PackTo(buffer, targetObject);
}
finally
{
    ArrayPool<byte>.Shared.Return(buffer);
}

最適化ポイント：コードジェネレータによる静的フォーマッタ生成、シリアライズ結果のキャッシュ、スパンベース処理の活用

10. Unity IL2CPP固有問題

IL2CPPビルドでAOTエラーが発生する場合は、ランタイムコード生成が制限されています。

対応策：

• 事前コード生成ツールMessagePack.Generatorを実行
• asmdefファイルでENABLE_IL2CPPを定義
• Unity専用パッケージMessagePack.Unityをインストール