"Size of hashkey has exceeded the maximum size limit of 2048 bytes": el tamaño de la clave hash ha excedido el límite máximo

TL;DR — DynamoDB longitudes de clave en mayúsculas: un valor de clave de partición (hash) puede tener como máximo 2048 bytes, y un valor de clave de clasificación (rango) como máximo 1024 bytes, medido como UTF-8 (o binario sin formato). Se rechaza una escritura cuya clave supere el límite. Acorte la clave: haga un hash de valores largos o mueva los datos voluminosos a un atributo que no sea clave.

Qué significa

ValidationException: One or more parameter values were invalid: Size of hashkey has exceeded the maximum size limit of2048 bytes

# sort-key variant:
ValidationException: One or more parameter values were invalid: Aggregated size of all range keys has exceeded the size limit of 1024 bytes

# on DynamoDB Local you get one combined sentence instead, naming neither key:
ValidationException: Hash primary key values must be under 2048 bytes, and range primary key values must be under 1024 bytes

(Sí, el espacio que falta en "of2048" está en el mensaje real del servicio.) Los atributos de clave están indexados y particionados físicamente por DynamoDB, así que su longitud está acotada muy por debajo del límite de Item de 400 KB. El valor de la clave de partición debe ser de 1 a 2048 bytes y el de la clave de ordenación de 1 a 1024 bytes. El recuento de bytes es el tamaño codificado (UTF-8 para cadenas, bytes en crudo para binario) — los caracteres multibyte cuentan por más de uno. Es un ValidationException HTTP 400, del lado del cliente, no reintentable hasta que la clave encoja.

Por qué ocurre

Una cadena larga como clave de partición — una URL, un documento completo, un blob codificado o una clave compuesta concatenada usados directamente como valor de la clave.
Una clave de ordenación compuesta verbosa — muchos segmentos unidos con # que juntos superan los 1024 bytes.
Datos en base64 / serializados en una clave — la codificación infla el recuento de bytes por encima del límite.
Texto multibyte — contenido no ASCII cuya codificación UTF-8 es mayor de lo que sugiere el recuento de caracteres.

Cómo solucionarlo

Aplica hash al valor largo — almacena un resumen determinista (p. ej. SHA-256, ~32 bytes) como clave y guarda el valor completo en un atributo separado que no sea clave.
Elige una clave más compacta — un identificador natural más corto en lugar del campo voluminoso.
Acorta la clave compuesta — recorta o abrevia los segmentos que componen una clave de ordenación unida con #.
Saca el contenido sobredimensionado de la clave a un atributo normal (que solo tiene que caber en el límite de Item de 400 KB).
Cuenta bytes UTF-8, no caracteres. Los emoji y el texto CJK se expanden rápido — una cadena de 500 caracteres puede superar los 2048 bytes.

Conéctate desde DynoTable

Pega los valores de clave que estés borroneando en la calculadora de tamaño de Item y comprueba los bytes contra los límites de 2048/1024 antes de escribir. En DynoTable, el staging (⌘S) detecta las claves sobredimensionadas en los Items de prueba que abras con ⌘K.

Cuando acortes claves compuestas, prototipa las consultas en el Query Builder. Cambia de perfil con ⌘P; Test Connection en Settings → Profiles. Consulta Conectar con AWS e Instalación.

Fuentes

Constraints in Amazon DynamoDB (verificado 2026-07-13)
Supported data types and naming rules (verificado 2026-07-13)

Errores relacionados

Item size has exceeded the maximum allowed size — el límite de 400 KB del Item entero (frente al límite por clave).
Item size to update has exceeded the maximum allowed size — un límite de tamaño de clave/índice durante una actualización.
ValidationException (resumen)
Aprende: Tamaño de Item y el límite de 400 KB · Claves primarias compuestas

Referencias

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.