The provided starting key is invalid

TL;DR — Seu ExclusiveStartKey não corresponde ao key schema do que você está paginando. Ele precisa conter exatamente os atributos de chave que o DynamoDB retornou em LastEvaluatedKey — a chave primária completa, mais a chave do índice quando você está consultando um GSI/LSI — com os mesmos nomes e tipos. Passe o LastEvaluatedKey de volta literalmente; montá-lo à mão é como isto quebra.

O que significa

ValidationException: The provided starting key is invalid

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

O ExclusiveStartKey diz a um Query/Scan onde retomar. O DynamoDB o valida contra o key schema da tabela — ou, para uma consulta de índice, a chave combinada índice-mais-tabela que o LastEvaluatedKey carrega. Atributos ausentes, atributos extras, nomes errados ou tipos errados, todos falham antes de qualquer dado ser lido.

Por que acontece

Construir a chave à mão com apenas a chave de partição — uma tabela de chave composta precisa da chave de partição e de ordenação na chave inicial.
Paginar um índice com apenas a chave da tabela — o LastEvaluatedKey em uma consulta de GSI/LSI contém tanto os atributos de chave do índice quanto a chave primária da tabela; todos eles precisam voltar.
Desvio de tipo ou nome — a chave foi serializada (JSON, parâmetro de URL, cache) e voltou com "42" onde o LastEvaluatedKey tinha um número, ou com um campo renomeado.
Reutilizar uma chave entre consultas — um LastEvaluatedKey de uma tabela/índice passado a uma consulta contra outra, ou à mesma consulta depois que a suposição de key schema mudou.
Um wrapper injetando padrões — um ODM que preenche atributos que ele acha que pertencem à chave pode inflar a chave inicial além do tamanho do schema.

Como corrigir

Faça round-trip do LastEvaluatedKey intocado:

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

Serialize-o sem perdas se ele cruzar um limite de requisição — quando o cursor de paginação vai para um browser e volta, codifique todo o objeto LastEvaluatedKey (por exemplo, base64 de seu JSON) em vez de reconstruí-lo a partir de campos do item, e mantenha os tipos numéricos como números.
Inclua todo atributo de chave para paginação de índice — chave de partição/ordenação do índice e chave de partição/ordenação da tabela, exatamente como retornado.
Não fabrique um ponto inicial — a paginação do DynamoDB não tem offset; se você precisa de "começar perto de X", expresse-o no KeyConditionExpression (sk > :x) em vez de um ExclusiveStartKey feito à mão.

Inspecionar o que o LastEvaluatedKey de fato contém para sua tabela ou índice tira a adivinhação — o app desktop DynoTable pagina através de consultas e mostra o cursor cru, e o DynamoDB Expression Builder compõe a requisição de consulta em torno dele.

Erros relacionados

The provided key element does not match the schema — a mesma incompatibilidade de schema em uma chave de GetItem/escrita.
Query key condition not supported
Exemplo de código: Get all items in Node.js · in Python (boto3) — o loop de paginação com LastEvaluatedKey feito corretamente.
Aprenda: Pagination in DynamoDB

Referências

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.