ValidationException: el tamaño del Item ha superado el máximo permitido

TL;DR — Un Item de DynamoDB puede ser como mucho de 400 KB (nombres de atributos + valores combinados). Tu escritura empuja un Item por encima de eso. Saca el campo grande (a S3, o repártelo entre varios Items) y almacena una referencia en su lugar.

Qué significa

ValidationException: Item size has exceeded the maximum allowed size

El límite es 400 KB = 409.600 bytes. Cuenta el Item entero: cada nombre de atributo más su valor, codificado en UTF-8, incluyendo la sobrecarga de mapas/listas anidados. Un UpdateItem que hace crecer un Item existente por encima de 400 KB falla del mismo modo (como actualización, el mensaje dice "Item size to update has exceeded the maximum allowed size").

Por qué ocurre

• Almacenar blobs grandes en línea — imágenes en base64, PDFs, documentos JSON grandes.
• Una lista/mapa sin límite (arrays de solo-adición, registros de eventos) que crece con el tiempo hasta cruzar los 400 KB.
• Nombres de atributos largos multiplicados a lo largo de un Item grande.
• Desnormalizar demasiado en un único Item.

Cómo solucionarlo

1. Descarga los valores grandes a S3. Almacena el objeto en S3 y guarda solo la clave/URL en DynamoDB. Es el patrón estándar para cualquier cosa que se acerque al límite.
2. Reparte los datos entre varios Items. Usa el patrón de colección de Items / partición vertical — una entidad lógica como varios Items que comparten una clave de partición.
3. Limita las colecciones que crecen. No dejes que un único Item acumule una lista sin límite; traslada las entradas a Items hijos con clave de ordenación.
4. Comprime el texto genuinamente grande antes de almacenarlo (gzip → atributo binario), si S3 no es una opción.

Ejemplo — patrón de referencia

// 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

¿Cuál es el tamaño máximo de Item en DynamoDB? 400 KB (409.600 bytes) por Item, contando cada nombre de atributo más su valor, codificado en UTF-8, incluyendo la sobrecarga de mapas y listas anidados. Un UpdateItem que hace crecer un Item existente por encima de 400 KB falla con el mismo error.

¿Cómo almaceno datos de más de 400 KB en DynamoDB? Descarga el valor grande a S3 y guarda solo la clave o la URL en DynamoDB, reparte los datos entre varios Items que compartan una clave de partición, o comprime el texto grande en un atributo binario. No dejes que un único Item acumule una lista sin límite.

Reproducirlo

Un único item que lleva un atributo de cadena de 410 KB, justo por encima del techo de 400 KB:

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

Salida real:

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

El mensaje nunca te dice por cuánto te has pasado, ni qué atributo lo provocó — así que cuando un item se ensambla a partir de varias fuentes, mídelo antes de escribir en lugar de ir por bisección después del rechazo.

Errores relacionados

• ItemCollectionSizeLimitExceededException — el límite de 10 GB de la colección (tablas con LSI).
• ValidationException (resumen)
• Aprende: Tamaño de Item y el límite de 400 KB · Colecciones de Items

Referencias

• 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 por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.

Reproducido el 2026-07-26 contra DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — la salida de arriba es literal.