DynamoDB SerializationException

TL;DR — DynamoDB n'a pas pu désérialiser le corps de la requête par rapport à son format filaire. Presque toujours une incohérence de wrapper de type : un nombre envoyé dans un wrapper de chaîne {"S": …} (ou l'inverse), une valeur qui n'est pas enveloppée dans un AttributeValue typé du tout, ou une forme bas niveau {S,N,BOOL,…} qui ne correspond pas à la valeur réelle. Corrige l'enveloppement de type — ou utilise le Document Client pour qu'il le fasse à ta place.

Ce que ça signifie

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

Contrairement à une ValidationException (levée après l'analyse de la requête), une SerializationException signifie que DynamoDB n'a pas réussi à lire le corps de la requête lui-même — la structure JSON ou un AttributeValue typé ne s'est pas désérialisé dans le type attendu par DynamoDB. Comme les autres erreurs client, elle revient avec un statut de classe HTTP 400, et elle n'est pas réessayable — renvoyer le même corps la reproduit.

Pourquoi ça arrive

Un nombre envoyé comme wrapper de chaîne — tu as placé une valeur numérique sous {"S": "123"} alors que l'attribut ou la clé est défini comme un nombre (N), ou l'inverse. Le message classique est NUMBER_VALUE cannot be converted to String.
Wrapper typé manquant — avec le DynamoDBClient bas niveau, tu as passé un {pk: "USER#1"} brut au lieu de {pk: {S: "USER#1"}}. L'API bas niveau exige que chaque valeur soit un AttributeValue typé.
Type erroné dans une clé — le wrapper {S}/{N} de l'attribut de clé ne correspond pas au type de clé déclaré de la table.
Une requête construite à la main (ou un proxy / Lambda qui remodèle le corps) qui émet un JSON AttributeValue malformé.
Confusion de la bibliothèque de marshalling — fournir du JSON DynamoDB déjà marshallé à un client qui le marshalle à nouveau (double enveloppement).

Comment le corriger

Utilise le Document Client (@aws-sdk/lib-dynamodb, ou le resource('dynamodb') de boto3). Il marshalle les valeurs natives en AttributeValues typés à ta place, ce qui élimine toute cette classe d'erreurs de wrapper.
Si tu dois utiliser le client bas niveau, enveloppe chaque valeur — {S: "…"} pour les chaînes, {N: "123"} pour les nombres (note : N est toujours une chaîne sur le fil), {BOOL: true}, {L: […]}, {M: {…}}.
Fais correspondre les types de clé au schéma — une clé définie comme N doit être envoyée comme {N: "…"}, jamais {S: …}.
Ne double-marshalle pas — passe des objets natifs au Document Client, ou des AttributeValues déjà typés au client bas niveau, jamais un mélange.

Tu construis sur le Document Client et ne touches plus jamais aux AttributeValues bruts ? L'éditeur d'éléments de DynoTable affiche la valeur typée à côté de chaque attribut — son mode DynamoDB-JSON révèle la forme filaire exacte — donc un nombre ou une chaîne mal typé saute aux yeux d'un coup d'œil.

FAQ

Qu'est-ce qui provoque une SerializationException dans DynamoDB ? Le corps de la requête ne s'est pas désérialisé par rapport au format filaire de DynamoDB — presque toujours une incohérence de wrapper de type, comme un nombre envoyé dans un wrapper de chaîne ({"S"}), ou une valeur brute passée au client bas niveau là où un AttributeValue typé ({S}/{N}/…) était requis.

En quoi SerializationException diffère-t-elle de ValidationException ? Une SerializationException se produit pendant que DynamoDB analyse le corps de la requête, avant qu'il ne valide le sens de la requête. Une ValidationException se produit après l'analyse, quand la requête bien formée enfreint une règle (expression incorrecte, incohérence de clé, limite de taille).

Erreurs liées

The provided key element does not match the schema — une incohérence de type de clé détectée à la validation.
ValidationException (overview)
En savoir plus : DynamoDB data types · JSON marshalling

Références

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.