DynamoDB SerializationException

TL;DR — DynamoDB がリクエストボディをそのワイヤーフォーマットに対してデシリアライズできませんでした。ほぼ必ず 型ラッパーの不一致 です: {"S": …} 文字列ラッパー内に送られた数値（またはその逆）、型付き AttributeValue にまったくラップされていない値、または実際の値と一致しない低レベルの {S,N,BOOL,…} 形状です。型のラッピングを修正する — または Document Client を使って代わりに行ってもらってください。

意味

SerializationException: NUMBER_VALUE cannot be converted to String
SerializationException: Start of structure or map found where not expected

（リクエストが解析された 後 に発生する）ValidationException とは異なり、SerializationException は DynamoDB がリクエストボディ自体の読み取りに失敗したことを意味します。JSON 構造や型付き AttributeValue が、DynamoDB が期待した型にデシリアライズされませんでした。他のクライアントエラーと同様に HTTP 400 クラスのステータスで返り、リトライ不可 です。同じボディを再送すると再現します。

発生する理由

• 数値が文字列ラッパーとして送られた — 属性やキーが数値（N）として定義されているのに数値を {"S": "123"} 配下に入れた、またはその逆。典型的なメッセージは NUMBER_VALUE cannot be converted to String です。
• 型付きラッパーの欠落 — 低レベルの DynamoDBClient で、{pk: {S: "USER#1"}} の代わりに素の {pk: "USER#1"} を渡した。低レベル API はすべての値が型付き AttributeValue であることを要求します。
• キー内の誤った型 — キー属性の {S}/{N} ラッパーがテーブルの宣言されたキー型と一致しない。
• 不正な形式の AttributeValue JSON を出力する 手作りのリクエスト（またはボディを作り直すプロキシ / Lambda）。
• マーシャリングライブラリの混乱 — すでにマーシャルされた DynamoDB JSON を、再びマーシャルするクライアントに渡す（二重ラッピング）。

修正方法

1. Document Client を使います（@aws-sdk/lib-dynamodb、または boto3 の resource('dynamodb')）。ネイティブの値を型付き AttributeValue に代わりにマーシャルするため、ラッパーのミスの種類全体を取り除きます。
2. 低レベルクライアントを使う必要がある場合は、すべての値をラップします — 文字列には {S: "…"}、数値には {N: "123"}（注意: N はワイヤー上では常に 文字列 です）、{BOOL: true}、{L: […]}、{M: {…}}。
3. キー型をスキーマに一致させます — N として定義されたキーは {N: "…"} として送る必要があり、決して {S: …} ではありません。
4. 二重マーシャルしないでください — ネイティブオブジェクトを Document Client に、またはすでに型付きの AttributeValue を低レベルクライアントに渡し、決して混在させないでください。

Document Client の上に構築し、生の AttributeValue に二度と触れませんか？DynoTable のアイテムエディタはすべての属性の横に型付きの値を表示し — DynamoDB-JSON モードは正確なワイヤー上の形を明らかにします — 型を誤った数値や文字列が一目瞭然です。

よくある質問

DynamoDB で SerializationException は何が原因ですか？ リクエストボディが DynamoDB のワイヤーフォーマットに対してデシリアライズされませんでした。ほぼ必ず型ラッパーの不一致で、文字列（{"S"}）ラッパー内に送られた数値、または型付き AttributeValue（{S}/{N}/…）が必要な場所で低レベルクライアントに渡された素の値などです。

SerializationException は ValidationException とどう違いますか？ SerializationException は、DynamoDB がリクエストの意味を検証する前に、リクエストボディを解析している間に発生します。ValidationException は解析後、正しい形式のリクエストがルール（不正な式、キーの不一致、サイズ制限）を破ったときに発生します。

関連するエラー

• The provided key element does not match the schema — 検証で捕捉されるキー型の不一致。
• ValidationException (overview)
• 学習: DynamoDB のデータ型 · JSON マーシャリング

参考資料

• Error handling with DynamoDB — Amazon DynamoDB Developer Guide
• AttributeValue — Amazon DynamoDB API Reference
• Supported data types and naming rules in Amazon DynamoDB — Amazon DynamoDB Developer Guide

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。