DynamoDB SerializationException

TL;DR — DynamoDB tidak dapat mendeserialisasi body permintaan terhadap format wire-nya. Hampir selalu ketidakcocokan pembungkus tipe: number dikirim di dalam pembungkus string {"S": …} (atau sebaliknya), nilai yang tidak dibungkus dalam AttributeValue bertipe sama sekali, atau bentuk low-level {S,N,BOOL,…} yang tidak cocok dengan nilai sebenarnya. Perbaiki pembungkusan tipe — atau gunakan Document Client agar dilakukan untuk Anda.

Apa artinya

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

Berbeda dengan ValidationException (yang dimunculkan setelah permintaan di-parse), SerializationException berarti DynamoDB gagal membaca body permintaan itu sendiri — struktur JSON atau AttributeValue bertipe tidak terdeserialisasi ke tipe yang diharapkan DynamoDB. Seperti kesalahan klien lain, ia kembali dengan status kelas HTTP 400, dan tidak dapat dicoba ulang — mengirim ulang body yang sama mereproduksinya.

Mengapa itu terjadi

• Number dikirim sebagai pembungkus string — Anda meletakkan nilai numerik di bawah {"S": "123"} di mana atribut atau kunci didefinisikan sebagai number (N), atau sebaliknya. Pesan klasiknya adalah NUMBER_VALUE cannot be converted to String.
• Kehilangan pembungkus bertipe — dengan DynamoDBClient low-level Anda meneruskan {pk: "USER#1"} mentah alih-alih {pk: {S: "USER#1"}}. API low-level mensyaratkan setiap nilai berupa AttributeValue bertipe.
• Tipe salah dalam kunci — pembungkus {S}/{N} atribut kunci tidak cocok dengan tipe kunci yang dideklarasikan tabel.
• Permintaan buatan tangan (atau proxy / Lambda yang membentuk ulang body) yang mengeluarkan JSON AttributeValue salah bentuk.
• Kebingungan library marshalling — memberi DynamoDB JSON yang sudah di-marshal ke klien yang me-marshal lagi (pembungkusan ganda).

Bagaimana cara memperbaikinya

1. Gunakan Document Client (@aws-sdk/lib-dynamodb, atau resource('dynamodb') boto3). Ia me-marshal nilai native ke AttributeValue bertipe untuk Anda, yang menghapus seluruh kelas kesalahan pembungkus.
2. Jika Anda harus menggunakan klien low-level, bungkus setiap nilai — {S: "…"} untuk string, {N: "123"} untuk number (catatan: N selalu string di wire), {BOOL: true}, {L: […]}, {M: {…}}.
3. Cocokkan tipe kunci ke schema — kunci yang didefinisikan sebagai N harus dikirim sebagai {N: "…"}, tidak pernah {S: …}.
4. Jangan marshal ganda — teruskan objek native ke Document Client, atau AttributeValue yang sudah bertipe ke klien low-level, tidak pernah campuran.

Membangun di atas Document Client dan tidak pernah menyentuh AttributeValue mentah lagi? Editor item DynoTable menunjukkan nilai bertipe di samping setiap atribut — mode DynamoDB-JSON-nya menyingkap bentuk wire yang persis — sehingga number atau string yang salah tipe jelas dalam sekejap.

FAQ

Apa yang menyebabkan SerializationException di DynamoDB? Body permintaan tidak terdeserialisasi terhadap format wire DynamoDB — hampir selalu ketidakcocokan pembungkus tipe, seperti number dikirim di dalam pembungkus string ({"S"}), atau nilai mentah diteruskan ke klien low-level di mana AttributeValue bertipe ({S}/{N}/…) diperlukan.

Bagaimana SerializationException berbeda dari ValidationException? SerializationException terjadi saat DynamoDB mem-parse body permintaan, sebelum ia memvalidasi makna permintaan. ValidationException terjadi setelah parsing, ketika permintaan yang berbentuk baik melanggar aturan (expression buruk, ketidakcocokan kunci, batas ukuran).

Kesalahan terkait

• The provided key element does not match the schema — ketidakcocokan tipe kunci tertangkap saat validasi.
• ValidationException (ikhtisar)
• Pelajari: DynamoDB data types · JSON marshalling

Referensi

• 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

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.