DynamoDB SerializationException

In breve — DynamoDB non è riuscito a deserializzare il corpo della richiesta rispetto al suo formato wire. Quasi sempre una mancata corrispondenza del wrapper di tipo: un numero inviato dentro un wrapper stringa {"S": …} (o viceversa), un valore che non è affatto racchiuso in un AttributeValue tipizzato, o una forma di basso livello {S,N,BOOL,…} che non corrisponde al valore effettivo. Correggi il wrapping di tipo — o usa il Document Client così viene fatto per te.

Cosa significa

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

A differenza di una ValidationException (che viene sollevata dopo che la richiesta è stata analizzata), una SerializationException significa che DynamoDB non è riuscito a leggere il corpo della richiesta stesso — la struttura JSON o un AttributeValue tipizzato non si è deserializzato nel tipo che DynamoDB si aspettava. Come altri errori client torna con uno stato di classe HTTP 400, e non è ripetibile — reinviare lo stesso corpo lo riproduce.

Perché succede

Numero inviato come wrapper stringa — hai messo un valore numerico sotto {"S": "123"} dove l'attributo o la chiave è definito come numero (N), o il contrario. Il messaggio classico è NUMBER_VALUE cannot be converted to String.
Wrapper tipizzato mancante — con il DynamoDBClient di basso livello hai passato un {pk: "USER#1"} grezzo invece di {pk: {S: "USER#1"}}. L'API di basso livello richiede che ogni valore sia un AttributeValue tipizzato.
Tipo errato in una chiave — il wrapper {S}/{N} dell'attributo chiave non corrisponde al tipo di chiave dichiarato della tabella.
Una richiesta costruita a mano (o un proxy / Lambda che rimodella il corpo) che emette JSON AttributeValue malformato.
Confusione della libreria di marshalling — passare DynamoDB JSON già marshallato a un client che marshalla di nuovo (doppio wrapping).

Come risolverlo

Usa il Document Client (@aws-sdk/lib-dynamodb, o resource('dynamodb') di boto3). Marshalla i valori nativi in AttributeValue tipizzati per te, il che elimina l'intera classe di errori di wrapper.
Se devi usare il client di basso livello, racchiudi ogni valore — {S: "…"} per le stringhe, {N: "123"} per i numeri (nota: N è sempre una stringa sul wire), {BOOL: true}, {L: […]}, {M: {…}}.
Fai corrispondere i tipi delle chiavi allo schema — una chiave definita come N deve essere inviata come {N: "…"}, mai {S: …}.
Non fare doppio marshalling — passa oggetti nativi al Document Client, o AttributeValue già tipizzati al client di basso livello, mai un mix.

Stai costruendo sul Document Client e non tocchi mai più gli AttributeValue grezzi? L'editor di item di DynoTable mostra il valore tipizzato accanto a ogni attributo — la sua modalità DynamoDB-JSON rivela l'esatta forma sul wire — così un numero o una stringa digitati male sono evidenti a colpo d'occhio.

FAQ

Cosa causa una SerializationException in DynamoDB? Il corpo della richiesta non si è deserializzato rispetto al formato wire di DynamoDB — quasi sempre una mancata corrispondenza del wrapper di tipo, come un numero inviato dentro un wrapper stringa ({"S"}), o un valore grezzo passato al client di basso livello dove era richiesto un AttributeValue tipizzato ({S}/{N}/…).

In cosa differisce SerializationException da ValidationException? Una SerializationException accade mentre DynamoDB sta analizzando il corpo della richiesta, prima di validare il significato della richiesta. Una ValidationException accade dopo l'analisi, quando la richiesta ben formata viola una regola (espressione errata, mancata corrispondenza della chiave, limite di dimensione).

Errori correlati

The provided key element does not match the schema — una mancata corrispondenza del tipo di chiave intercettata alla validazione.
ValidationException (overview)
Impara: DynamoDB data types · JSON marshalling

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.