DynoTable

DynamoDB SerializationException

TL;DR — O DynamoDB não conseguiu desserializar o corpo da requisição contra seu formato de fio. Quase sempre uma incompatibilidade de wrapper de tipo: um número enviado dentro de um wrapper de string {"S": …} (ou vice-versa), um valor que não está envolvido em um AttributeValue tipado, ou uma forma de baixo nível {S,N,BOOL,…} que não corresponde ao valor real. Corrija o envolvimento de tipo — ou use o Document Client para que seja feito por você.

O que significa

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

Ao contrário de um ValidationException (que é levantado depois que a requisição faz parse), um SerializationException significa que o DynamoDB falhou ao ler o próprio corpo da requisição — a estrutura JSON ou um AttributeValue tipado não desserializou no tipo que o DynamoDB esperava. Como outros erros de cliente, ele volta com um status da classe HTTP 400, e é não retentável — reenviar o mesmo corpo o reproduz.

Por que isso acontece

  • Número enviado como wrapper de string — você colocou um valor numérico sob {"S": "123"} onde o atributo ou chave é definido como número (N), ou o inverso. A mensagem clássica é NUMBER_VALUE cannot be converted to String.
  • Faltar o wrapper tipado — com o DynamoDBClient de baixo nível você passou um {pk: "USER#1"} cru em vez de {pk: {S: "USER#1"}}. A API de baixo nível exige que todo valor seja um AttributeValue tipado.
  • Tipo errado em uma chave — o wrapper {S}/{N} do atributo de chave não corresponde ao tipo de chave declarado da tabela.
  • Uma requisição construída à mão (ou um proxy / Lambda que remodela o corpo) que emite JSON de AttributeValue malformado.
  • Confusão de biblioteca de marshalling — alimentar DynamoDB JSON já feito marshal a um cliente que faz marshal novamente (envolvimento duplo).

Como corrigir

  1. Use o Document Client (@aws-sdk/lib-dynamodb, ou o resource('dynamodb') do boto3). Ele faz marshal de valores nativos para AttributeValues tipados por você, o que remove toda a classe de erros de wrapper.
  2. Se você precisa usar o cliente de baixo nível, envolva todo valor — {S: "…"} para strings, {N: "123"} para números (nota: N é sempre uma string no fio), {BOOL: true}, {L: […]}, {M: {…}}.
  3. Combine os tipos de chave com o schema — uma chave definida como N precisa ser enviada como {N: "…"}, nunca {S: …}.
  4. Não faça marshal duplo — passe objetos nativos ao Document Client, ou AttributeValues já tipados ao cliente de baixo nível, nunca uma mistura.

Construindo sobre o Document Client e nunca tocando AttributeValues crus novamente? O editor de itens do DynoTable mostra o valor tipado ao lado de cada atributo — seu modo DynamoDB-JSON revela a forma exata de fio — para que um número ou string mal tipado seja óbvio num relance.

FAQ

O que causa um SerializationException no DynamoDB? O corpo da requisição não desserializou contra o formato de fio do DynamoDB — quase sempre uma incompatibilidade de wrapper de tipo, como um número enviado dentro de um wrapper de string ({"S"}), ou um valor cru passado ao cliente de baixo nível onde um AttributeValue tipado ({S}/{N}/…) era obrigatório.

Como o SerializationException difere do ValidationException? Um SerializationException acontece enquanto o DynamoDB está fazendo parse do corpo da requisição, antes de validar o significado da requisição. Um ValidationException acontece após o parse, quando a requisição bem formada quebra uma regra (expressão ruim, incompatibilidade de chave, limite de tamanho).

Erros relacionados

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.

Trabalhe com o DynamoDB sem o Console

Um cliente desktop rápido para DynamoDB que roda o SQL de verdade que o DynamoDB não consegue — JOINs, GROUP BY, agregações — com edição visual e um agente de IA com suas próprias chaves do Bedrock.

BaixarVer preços

Teste grátis de 30 dias, sem cartão de crédito — depois o plano Grátis sem limite de tempo.