DynamoDB SerializationException

TL;DR — DynamoDB, isteği kablo biçimine karşı çözemedi. Neredeyse her zaman bir tür-sarmalayıcı uyuşmazlığı: bir {"S": …} string sarmalayıcısı içinde gönderilen bir sayı (ya da tersi), tür etiketli bir AttributeValue içine hiç sarılmamış bir değer ya da gerçek değerle eşleşmeyen düşük seviyeli bir {S,N,BOOL,…} şekli. Tür sarmalamasını düzeltin — ya da sizin için yapılması için Document Client'ı kullanın.

Ne anlama gelir

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

Bir ValidationException'ın (istek ayrıştırıldıktan sonra fırlatılan) aksine, bir SerializationException, DynamoDB'nin isteğin kendisini okuyamadığı anlamına gelir — JSON yapısı ya da bir tür etiketli AttributeValue, DynamoDB'nin beklediği türe çözülmedi. Diğer istemci hataları gibi bir HTTP 400 sınıfı durumla geri gelir ve yeniden denenebilir değildir — aynı gövdeyi yeniden göndermek onu yeniden üretir.

Neden olur

• Bir string sarmalayıcısı olarak gönderilen sayı — öznitelik ya da anahtar bir sayı (N) olarak tanımlıyken sayısal bir değeri {"S": "123"} altına koydunuz ya da tersi. Klasik mesaj NUMBER_VALUE cannot be converted to String'dir.
• Tür etiketli sarmalayıcının eksik olması — düşük seviyeli DynamoDBClient ile {pk: {S: "USER#1"}} yerine çıplak bir {pk: "USER#1"} ilettiniz. Düşük seviyeli API, her değerin bir tür etiketli AttributeValue olmasını gerektirir.
• Bir anahtarda yanlış tür — anahtar özniteliğinin {S}/{N} sarmalayıcısı tablonun bildirilen anahtar türüyle eşleşmiyor.
• Hatalı biçimlendirilmiş AttributeValue JSON'u yayan elle oluşturulmuş bir istek (ya da gövdeyi yeniden şekillendiren bir proxy / Lambda).
• Marshal kitaplığı karışıklığı — zaten marshal edilmiş DynamoDB JSON'unu tekrar marshal eden bir istemciye beslemek (çift sarmalama).

Nasıl düzeltilir

1. Document Client'ı kullanın (@aws-sdk/lib-dynamodb ya da boto3'ün resource('dynamodb')'i). Yerel değerleri sizin için tür etiketli AttributeValue'lara marshal eder, ki bu tüm sarmalayıcı hataları sınıfını kaldırır.
2. Düşük seviyeli istemciyi kullanmanız gerekiyorsa, her değeri sarın — stringler için {S: "…"}, sayılar için {N: "123"} (not: N kabloda her zaman bir stringdir), {BOOL: true}, {L: […]}, {M: {…}}.
3. Anahtar türlerini şemayla eşleştirin — N olarak tanımlanmış bir anahtar {N: "…"} olarak gönderilmelidir, asla {S: …} değil.
4. Çift marshal etmeyin — yerel nesneleri Document Client'a ya da zaten türlü AttributeValue'ları düşük seviyeli istemciye iletin, asla bir karışım değil.

Document Client üzerine kurup çıplak AttributeValue'lara bir daha dokunmuyor musunuz? DynoTable'ın öğe düzenleyicisi, her özniteliğin yanında türlü değeri gösterir — DynamoDB-JSON kipi tam kablo biçimini ortaya çıkarır — böylece yanlış türlenmiş bir sayı ya da string bir bakışta bellidir.

SSS

DynamoDB'de bir SerializationException'a ne neden olur? İstek gövdesi, DynamoDB'nin kablo biçimine karşı çözülmedi — neredeyse her zaman bir tür-sarmalayıcı uyuşmazlığı, örneğin bir string ({"S"}) sarmalayıcısı içinde gönderilen bir sayı ya da tür etiketli bir AttributeValue'nun ({S}/{N}/…) gerektiği yerde düşük seviyeli istemciye iletilen çıplak bir değer.

SerializationException, ValidationException'dan nasıl farklıdır? Bir SerializationException, DynamoDB isteğin anlamını doğrulamadan önce istek gövdesini ayrıştırırken olur. Bir ValidationException, ayrıştırmadan sonra, iyi biçimlendirilmiş istek bir kuralı bozduğunda (hatalı ifade, anahtar uyuşmazlığı, boyut sınırı) olur.

İlgili hatalar

• The provided key element does not match the schema — doğrulamada yakalanan bir anahtar türü uyuşmazlığı.
• ValidationException (genel bakış)
• Öğrenin: DynamoDB data types · JSON marshalling

Kaynaklar

• 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

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.