ValidationException: Item size has exceeded the maximum allowed size

In breve — Un Item DynamoDB può essere al massimo di 400 KB (nomi degli attributi + valori combinati). La tua scrittura spinge un Item oltre. Sposta il campo grande fuori (su S3, o suddividilo tra più Item) e memorizza invece un riferimento.

Cosa significa

ValidationException: Item size has exceeded the maximum allowed size

Il limite è 400 KB = 409.600 byte. Conta l'intero Item: ogni nome di attributo più il suo valore, codificato UTF-8, incluso l'overhead di mappe/liste nidificate. Un UpdateItem che fa crescere un Item esistente oltre i 400 KB fallisce allo stesso modo (come aggiornamento, il messaggio recita "Item size to update has exceeded the maximum allowed size").

Perché succede

• Memorizzare grandi blob inline — immagini base64, PDF, grandi documenti JSON.
• Una lista/mappa illimitata (array append-only, log di eventi) che cresce nel tempo finché non supera i 400 KB.
• Nomi di attributo lunghi moltiplicati su un Item grande.
• Denormalizzare troppo in un singolo Item.

Come risolverlo

1. Scarica i valori grandi su S3. Memorizza l'oggetto in S3 e tieni solo la chiave/URL in DynamoDB. Questo è il pattern standard per qualsiasi cosa si avvicini al limite.
2. Suddividi i dati tra più Item. Usa il pattern item-collection / partizione verticale — un'entità logica come diversi Item che condividono una partition key.
3. Limita le collezioni in crescita. Non lasciare che un singolo Item accumuli una lista illimitata; sposta le voci in Item figli indicizzati per sort key.
4. Comprimi il testo genuinamente grande prima di memorizzarlo (gzip → attributo binario), se S3 non è un'opzione.

Esempio — pattern di riferimento

// 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 è la dimensione massima di un Item in DynamoDB? 400 KB (409.600 byte) per Item, contando ogni nome di attributo più il suo valore, codificato UTF-8, incluso l'overhead di mappe e liste nidificate. Un UpdateItem che fa crescere un Item esistente oltre i 400 KB fallisce con lo stesso errore.

Come memorizzo dati più grandi di 400 KB in DynamoDB? Scarica il valore grande su S3 e tieni solo la chiave o l'URL in DynamoDB, suddividi i dati tra più Item che condividono una partition key, o comprimi il testo grande in un attributo binario. Non lasciare che un singolo Item accumuli una lista illimitata.

Riproducilo

Un singolo Item che porta un attributo stringa da 410 KB, appena oltre il tetto dei 400 KB:

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

Output reale:

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

Il messaggio non ti dice mai di quanto hai superato il limite, né quale attributo lo ha causato — quindi, quando un Item viene assemblato da più fonti, misuralo prima di scriverlo invece di procedere per bisezione dopo il rifiuto.

Errori correlati

• ItemCollectionSizeLimitExceededException — il limite di 10 GB della collezione (tabelle con LSI).
• ValidationException (overview)
• Impara: Item size & the 400 KB limit · Item collections

Riferimenti

• 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

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.

Riprodotto il 2026-07-26 su DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — l'output qui sopra è riportato alla lettera.