DynamoDB SerializationException

TL;DR — DynamoDB couldn't deserialize the request body against its wire format. Almost always a type-wrapper mismatch: a number sent inside a {"S": …} string wrapper (or vice-versa), a value that isn't wrapped in a typed AttributeValue at all, or a low-level {S,N,BOOL,…} shape that doesn't match the actual value. Fix the type wrapping — or use the Document Client so it's done for you.

What it means

SerializationException: NUMBER_VALUE cannot be converted to String
SerializationException: class java.lang.String cannot be converted to an integer

Unlike a ValidationException (which is raised after the request parses), a SerializationException means DynamoDB failed to read the request body itself — the JSON structure or a typed AttributeValue didn't deserialize into the type DynamoDB expected. It's an HTTP 400, client-side, and not retryable — resending the same body reproduces it.

Why it happens

• Number sent as a string wrapper — you put a numeric value under {"S": "123"} where the attribute or key is defined as a number (N), or the reverse. The classic message is NUMBER_VALUE cannot be converted to String.
• Missing the typed wrapper — with the low-level DynamoDBClient you passed a raw {pk: "USER#1"} instead of {pk: {S: "USER#1"}}. The low-level API requires every value to be a typed AttributeValue.
• Wrong type in a key — the key attribute's {S}/{N} wrapper doesn't match the table's declared key type.
• A hand-built request (or a proxy / Lambda that reshapes the body) that emits malformed AttributeValue JSON.
• Marshalling library confusion — feeding already-marshalled DynamoDB JSON to a client that marshals again (double-wrapping).

How to fix it

1. Use the Document Client (@aws-sdk/lib-dynamodb, or boto3's resource('dynamodb')). It marshals native values to typed AttributeValues for you, which removes the whole class of wrapper mistakes.
2. If you must use the low-level client, wrap every value — {S: "…"} for strings, {N: "123"} for numbers (note: N is always a string on the wire), {BOOL: true}, {L: […]}, {M: {…}}.
3. Match key types to the schema — a key defined as N must be sent as {N: "…"}, never {S: …}.
4. Don't double-marshal — pass native objects to the Document Client, or already-typed AttributeValues to the low-level client, never a mix.

Building on the Document Client and never touching raw AttributeValues again? The DynoTable desktop app shows the typed value alongside every attribute so a mistyped number or string is obvious at a glance.

FAQ

What causes a SerializationException in DynamoDB? The request body didn't deserialize against DynamoDB's wire format — almost always a type-wrapper mismatch, such as a number sent inside a string ({"S"}) wrapper, or a raw value passed to the low-level client where a typed AttributeValue ({S}/{N}/…) was required.

How is SerializationException different from ValidationException? A SerializationException happens while DynamoDB is parsing the request body, before it validates the request's meaning. A ValidationException happens after parsing, when the well-formed request breaks a rule (bad expression, key mismatch, size limit).

Related errors

• The provided key element does not match the schema — a key type mismatch caught at validation.
• ValidationException (overview)
• Learn: DynamoDB data types · JSON marshalling