DynamoDB SerializationException

TL;DR — DynamoDB konnte den Request-Body nicht gegen sein Wire-Format deserialisieren. Fast immer ein Typ-Wrapper-Konflikt: eine Zahl, die in einem {"S": …}-String-Wrapper gesendet wird (oder umgekehrt), ein Wert, der gar nicht in einem typisierten AttributeValue gewrappt ist, oder eine Low-Level-{S,N,BOOL,…}-Form, die nicht zum tatsächlichen Wert passt. Behebe das Typ-Wrapping — oder nutze den Document Client, damit es für dich erledigt wird.

Was es bedeutet

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

Anders als eine ValidationException (die nachdem der Request geparst wurde ausgelöst wird), bedeutet eine SerializationException, dass DynamoDB den Request-Body selbst nicht lesen konnte — die JSON-Struktur oder ein typisiertes AttributeValue ließ sich nicht in den von DynamoDB erwarteten Typ deserialisieren. Wie andere Client-Fehler kommt er mit einem HTTP-400-Klasse-Status zurück und ist nicht wiederholbar — dasselbe Body erneut zu senden reproduziert ihn.

Warum es passiert

• Zahl als String-Wrapper gesendet — du hast einen numerischen Wert unter {"S": "123"} abgelegt, wo das Attribut oder der Schlüssel als Zahl (N) definiert ist, oder umgekehrt. Die klassische Meldung ist NUMBER_VALUE cannot be converted to String.
• Fehlender typisierter Wrapper — mit dem Low-Level-DynamoDBClient hast du ein rohes {pk: "USER#1"} statt {pk: {S: "USER#1"}} übergeben. Die Low-Level-API verlangt, dass jeder Wert ein typisiertes AttributeValue ist.
• Falscher Typ in einem Schlüssel — der {S}/{N}-Wrapper des Schlüsselattributs passt nicht zum deklarierten Schlüsseltyp der Tabelle.
• Ein von Hand gebauter Request (oder ein Proxy / eine Lambda, die den Body umformt), der fehlerhaftes AttributeValue-JSON ausgibt.
• Verwirrung durch Marshalling-Bibliotheken — bereits gemarshalltes DynamoDB-JSON in einen Client einspeisen, der erneut marshallt (doppeltes Wrapping).

So behebst du es

1. Nutze den Document Client (@aws-sdk/lib-dynamodb oder boto3s resource('dynamodb')). Er marshallt native Werte für dich zu typisierten AttributeValues, was die ganze Klasse von Wrapper-Fehlern beseitigt.
2. Falls du den Low-Level-Client verwenden musst, wrappe jeden Wert — {S: "…"} für Strings, {N: "123"} für Zahlen (Hinweis: N ist im Wire-Format immer ein String), {BOOL: true}, {L: […]}, {M: {…}}.
3. Bringe Schlüsseltypen mit dem Schema in Einklang — ein als N definierter Schlüssel muss als {N: "…"} gesendet werden, nie {S: …}.
4. Marshalle nicht doppelt — übergib native Objekte an den Document Client oder bereits typisierte AttributeValues an den Low-Level-Client, nie eine Mischung.

Baust du auf dem Document Client auf und fasst nie wieder rohe AttributeValues an? DynoTables Item-Editor zeigt den typisierten Wert neben jedem Attribut — sein DynamoDB-JSON-Modus legt die exakte Wire-Form offen — sodass eine falsch typisierte Zahl oder ein String auf einen Blick auffällt.

FAQ

Was verursacht eine SerializationException in DynamoDB? Der Request-Body ließ sich nicht gegen das Wire-Format von DynamoDB deserialisieren — fast immer ein Typ-Wrapper-Konflikt, etwa eine Zahl, die in einem String-({"S"})-Wrapper gesendet wird, oder ein roher Wert, der an den Low-Level-Client übergeben wird, wo ein typisiertes AttributeValue ({S}/{N}/…) erforderlich war.

Wie unterscheidet sich SerializationException von ValidationException? Eine SerializationException passiert, während DynamoDB den Request-Body parst, bevor es die Bedeutung des Requests validiert. Eine ValidationException passiert nach dem Parsen, wenn der wohlgeformte Request eine Regel bricht (schlechte Expression, Schlüssel-Konflikt, Größenlimit).

Verwandte Fehler

• The provided key element does not match the schema — ein bei der Validierung erkannter Schlüsseltyp-Konflikt.
• ValidationException (Überblick)
• Learn: DynamoDB-Datentypen · JSON-Marshalling

Referenzen

• 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

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.