The provided starting key is invalid

TL;DR — Tu ExclusiveStartKey no coincide con el esquema de claves de lo que estás paginando. Debe contener exactamente los atributos de clave que DynamoDB devolvió en LastEvaluatedKey — la clave primaria completa, más la clave del índice cuando consultas un GSI/LSI — con los mismos nombres y tipos. Devuelve LastEvaluatedKey tal cual; ensamblarlo a mano es lo que lo 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

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);

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

Inspeccionar lo que LastEvaluatedKey contiene realmente para tu tabla o índice elimina las conjeturas — la aplicación de escritorio DynoTable pagina a través de las consultas y muestra el cursor en bruto, y el DynamoDB Expression Builder compone la petición de consulta a su alrededor.

Errores relacionados

The provided key element does not match the schema — el mismo desajuste de esquema en una clave de GetItem/escritura.
Query key condition not supported
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

References

Última verificación el 2026-07-13 con la documentación oficial de AWS enlazada arriba.