ValidationException: Item size has exceeded the maximum allowed size

TL;DR — Um item do DynamoDB pode ter no máximo 400 KB (nomes de atributo + valores combinados). Sua escrita empurra um item além disso. Mova o campo grande para fora (para o S3, ou divida entre itens) e armazene uma referência em vez disso.

O que significa

ValidationException: Item size has exceeded the maximum allowed size

O limite é 400 KB = 409.600 bytes. Ele conta o item inteiro: todo nome de atributo mais seu valor, codificado em UTF-8, incluindo o overhead de map/list aninhado. Um UpdateItem que faz um item existente crescer além de 400 KB falha da mesma forma (como uma atualização, a mensagem diz "Item size to update has exceeded the maximum allowed size").

Por que isso acontece

• Armazenar blobs grandes inline — imagens base64, PDFs, documentos JSON grandes.
• Uma list/map ilimitada (arrays somente-append, logs de eventos) que cresce ao longo do tempo até cruzar 400 KB.
• Nomes de atributo longos multiplicados por um item grande.
• Desnormalizar demais em um único item.

Como corrigir

1. Descarregue valores grandes para o S3. Armazene o objeto no S3 e mantenha apenas a chave/URL no DynamoDB. Este é o padrão consagrado para qualquer coisa se aproximando do limite.
2. Divida os dados entre múltiplos itens. Use o padrão de item-collection / partição vertical — uma entidade lógica como vários itens compartilhando uma chave de partição.
3. Limite coleções que crescem. Não deixe um único item acumular uma list ilimitada; agrupe entradas em itens filhos chaveados por chave de ordenação.
4. Comprima texto genuinamente grande antes de armazenar (gzip → atributo binário), se o S3 não é uma opção.

Exemplo — padrão de referência

// Instead of storing the blob inline, store an S3 pointer:
await doc.send(
  new PutCommand({
    TableName: 'Documents',
    Item: {
      pk: 'DOC#1',
      title: 'Q3 report',
      s3Key: 'documents/DOC#1/report.pdf', // the bytes live in S3
      sizeBytes: 2_400_000
    }
  })
);

FAQ

Qual é o tamanho máximo de item no DynamoDB? 400 KB (409.600 bytes) por item, contando todo nome de atributo mais seu valor, codificado em UTF-8, incluindo o overhead de map e list aninhados. Um UpdateItem que faz um item existente crescer além de 400 KB falha com o mesmo erro.

Como armazeno dados maiores que 400 KB no DynamoDB? Descarregue o valor grande para o S3 e mantenha apenas a chave ou URL no DynamoDB, divida os dados entre múltiplos itens que compartilham uma chave de partição, ou comprima texto grande em um atributo binário. Não deixe um único item acumular uma list ilimitada.

Reproduza

Um único item carregando um atributo string de 410 KB, logo acima do teto de 400 KB:

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'BIG'}, sk: {S: 'META'}, blob: {S: 'x'.repeat(410 * 1024)}}
  })
);

Saída real:

ValidationException: Item size has exceeded the maximum allowed size
HTTP 400

A mensagem nunca diz o quanto você passou do limite, nem qual atributo causou isso — então, quando um item é montado a partir de várias fontes, meça antes de escrever em vez de ir eliminando candidatos depois da rejeição.

Erros relacionados

• ItemCollectionSizeLimitExceededException — o limite de coleção de 10 GB (tabelas com LSI).
• ValidationException (overview)
• Aprenda: Item size & the 400 KB limit · Item collections

Referências

• Supported data types and naming rules in Amazon DynamoDB — Developer Guide
• BatchWriteItem — Amazon DynamoDB API Reference
• TransactWriteItems — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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

Reproduzido em 2026-07-26 no DynamoDB Local 2.x com o AWS SDK for JavaScript v3.1095.0 — a saída acima é literal.