La clave de inicio proporcionada no es válida

TL;DR: Tu ExclusiveStartKey no coincide con la clave schema de lo que estás paginando. Debe contener exactamente los atributos clave DynamoDB devueltos en LastEvaluatedKey: la clave principal completa, más la clave de índice cuando query completa un GSI/LSI, con los mismos nombres y tipos. Pase LastEvaluatedKey palabra por palabra; ensamblarlo a mano es como esto se rompe.

Qué significa

ValidationException: The provided starting key is invalid

ValidationException: Exclusive Start Key must have same size as table's key schema

ExclusiveStartKey le indica a un Query/Scan dónde reanudar. DynamoDB lo valida contra el esquema de claves de la tabla — o, para una consulta de índice, la clave combinada de índice más tabla que lleva LastEvaluatedKey. Atributos que faltan, atributos de más, nombres incorrectos o tipos incorrectos fallan todos antes de leer ningún dato.

Por qué ocurre

• Construir la clave a mano solo con la clave de partición — una tabla con clave compuesta necesita la clave de partición y la de ordenación en la clave de inicio.
• Paginar un índice solo con la clave de la tabla — el LastEvaluatedKey de una consulta a un GSI/LSI contiene tanto los atributos de la clave del índice como la clave primaria de la tabla; todos ellos deben volver.
• Deriva de tipos o nombres — la clave se serializó (JSON, parámetro de URL, caché) y volvió con "42" donde LastEvaluatedKey tenía un número, o con un campo renombrado.
• Reutilizar una clave entre consultas — un LastEvaluatedKey de una tabla/índice pasado a una consulta contra otra, o a la misma consulta después de que cambiara la suposición sobre el esquema de claves.
• Un wrapper que inyecta valores por defecto — un ODM que rellena atributos que cree que pertenecen a la clave puede inflar la clave de inicio más allá del tamaño del esquema.

Cómo solucionarlo

1. Reenvía LastEvaluatedKey sin tocarlo:

   let ExclusiveStartKey;
   do {
     const page = await docClient.send(
       new QueryCommand({
         TableName,
         KeyConditionExpression,
         ExpressionAttributeValues,
         ExclusiveStartKey
       })
     );
     items.push(...(page.Items ?? []));
     ExclusiveStartKey = page.LastEvaluatedKey; // verbatim — no rebuild
   } while (ExclusiveStartKey);

   CopiarCopiado

2. Serialízalo sin pérdidas si cruza el límite de una petición — cuando el cursor de paginación va a un navegador y vuelve, codifica el objeto LastEvaluatedKey completo (p. ej. base64 de su JSON) en lugar de reconstruirlo a partir de los campos del Item, y mantén los tipos numéricos como números.

3. Incluye cada atributo de clave para la paginación de índices — clave de partición/ordenación del índice y clave de partición/ordenación de la tabla, exactamente como se devolvieron.

4. No inventes un punto de inicio — la paginación de DynamoDB no tiene desplazamiento (offset); si necesitas "empezar cerca de X", exprésalo en el KeyConditionExpression (sk > :x) en lugar de un ExclusiveStartKey hecho a mano.

5. Registra el LastEvaluatedKey en bruto cuando falle. Compáralo byte a byte con lo que envía tu siguiente petición — las capas de serialización a menudo renombran o convierten en cadena los tipos numéricos.

Consulta en DynoTable

Pagina una Query en DynoTable e inspecciona el cursor LastEvaluatedKey en bruto entre páginas — abre la tabla con ⌘K, ejecuta una Query y copia el token de paginación tal cual en tu bucle del SDK. El panel de consulta muestra exactamente qué atributos de clave espera DynamoDB.

Usa el Query Builder para generar un programa de Query paginado con el manejo correcto de ExclusiveStartKey. Cambia de perfil con ⌘P; Test Connection en Ajustes → Perfiles. Consulta Conectar con AWS e Instalación.

Fuentes

• Paginating table query results in DynamoDB (verificado el 2026-07-13)
• Query — Amazon DynamoDB API Reference (verificado el 2026-07-13)

Errores relacionados

• The provided key element does not match the schema — el mismo desajuste de esquema en una clave de GetItem/escritura.
• Condición de clave de Query no admitida
• Ejemplo de código: Get all items in Node.js · en Python (boto3) — el bucle de paginación con LastEvaluatedKey hecho bien.
• Aprende: Pagination in DynamoDB

Referencias

• Paginating table query results in DynamoDB — Amazon DynamoDB Developer Guide
• Query — Amazon DynamoDB API Reference
• Scan — Amazon DynamoDB API Reference

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