DynamoDB SerializationException

TL;DR — DynamoDB no pudo deserializar el cuerpo de la petición según su formato de transferencia. Casi siempre un desajuste de envoltorio de tipo: un número enviado dentro de un envoltorio de cadena {"S": …} (o viceversa), un valor que no está envuelto en un AttributeValue tipado en absoluto, o una forma de bajo nivel {S,N,BOOL,…} que no coincide con el valor real. Corrige el envoltorio de tipo — o usa el Document Client para que se haga por ti.

Qué significa

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

A diferencia de un ValidationException (que se lanza después de que la petición se analice), un SerializationException significa que DynamoDB no pudo leer el propio cuerpo de la petición — la estructura JSON o un AttributeValue tipado no se deserializó al tipo que DynamoDB esperaba. Como otros errores del cliente, vuelve con un estado de clase HTTP 400, y no es reintentable — reenviar el mismo cuerpo lo reproduce.

Por qué ocurre

Número enviado como envoltorio de cadena — pusiste un valor numérico bajo {"S": "123"} donde el atributo o la clave está definido como número (N), o al revés. El mensaje clásico es NUMBER_VALUE cannot be converted to String.
Falta el envoltorio tipado — con el DynamoDBClient de bajo nivel pasaste un {pk: "USER#1"} en bruto en lugar de {pk: {S: "USER#1"}}. La API de bajo nivel requiere que cada valor sea un AttributeValue tipado.
Tipo equivocado en una clave — el envoltorio {S}/{N} del atributo de clave no coincide con el tipo de clave declarado de la tabla.
Una petición construida a mano (o un proxy / Lambda que reforma el cuerpo) que emite JSON de AttributeValue mal formado.
Confusión con la librería de marshalling — alimentar JSON de DynamoDB ya marshalled a un cliente que vuelve a marshalarlo (doble envoltorio).

Cómo solucionarlo

Usa el Document Client (@aws-sdk/lib-dynamodb, o el resource('dynamodb') de boto3). Marshalizar los valores nativos a AttributeValues tipados por ti, lo que elimina toda esta clase de errores de envoltorio.
Si debes usar el cliente de bajo nivel, envuelve cada valor — {S: "…"} para cadenas, {N: "123"} para números (nota: N es siempre una cadena en la transferencia), {BOOL: true}, {L: […]}, {M: {…}}.
Haz coincidir los tipos de clave con el esquema — una clave definida como N debe enviarse como {N: "…"}, nunca {S: …}.
No hagas doble marshalling — pasa objetos nativos al Document Client, o AttributeValues ya tipados al cliente de bajo nivel, nunca una mezcla.

¿Construyendo sobre el Document Client y sin volver a tocar AttributeValues en bruto? El editor de Items de DynoTable muestra el valor tipado junto a cada atributo — su modo DynamoDB-JSON revela la forma exacta en el cable — así que un número o una cadena mal tipados saltan a la vista.

FAQ

¿Qué causa un SerializationException en DynamoDB? El cuerpo de la petición no se deserializó según el formato de transferencia de DynamoDB — casi siempre un desajuste de envoltorio de tipo, como un número enviado dentro de un envoltorio de cadena ({"S"}), o un valor en bruto pasado al cliente de bajo nivel donde se requería un AttributeValue tipado ({S}/{N}/…).

¿En qué se diferencia SerializationException de ValidationException? Un SerializationException ocurre mientras DynamoDB analiza el cuerpo de la petición, antes de validar el significado de la petición. Un ValidationException ocurre después del análisis, cuando la petición bien formada rompe una regla (expresión incorrecta, desajuste de clave, límite de tamaño).

Errores relacionados

The provided key element does not match the schema — un desajuste de tipo de clave detectado en la validación.
ValidationException (descripción general)
Aprende: DynamoDB data types · JSON marshalling

Referencias

Última verificación el 2026-07-13 con la documentación oficial de AWS enlazada arriba.