A chave inicial fornecida é inválida

TL;DR — Seu ExclusiveStartKey não corresponde ao esquema principal do que você está paginando. Ele deve conter exatamente os atributos de chave DynamoDB retornados em LastEvaluatedKey — a chave primária completa, mais a chave de índice quando você está consultando um GSI/LSI — com os mesmos nomes e tipos. Passe LastEvaluatedKey de volta literalmente; montando à mão é assim que isso quebra.

O que significa

ValidationException: The provided starting key is invalid

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

ExclusiveStartKey informa ao Query/Scan onde retomar. O DynamoDB o valida em relação ao esquema de chave da tabela – ou, para uma consulta de índice, a chave combinada de índice mais tabela que o LastEvaluatedKey carrega. Atributos ausentes, atributos extras, nomes errados ou tipos errados falham antes que qualquer dado seja lido.

Por que isso acontece

Construir manualmente a chave apenas com a chave de partição — uma tabela de chave composta precisa de uma chave de partição e de classificação na chave inicial.
Paginando um índice apenas com a chave da tabela — LastEvaluatedKey em uma consulta GSI/LSI contém os atributos da chave do índice e a chave primária da tabela; todos eles devem voltar.
Desvio de tipo ou nome — a chave foi serializada (JSON, parâmetro URL, cache) e voltou com "42" onde LastEvaluatedKey tinha um número, ou com um campo renomeado.
Reutilizar uma chave entre consultas — um LastEvaluatedKey de uma tabela/index passado para uma consulta em outra ou para a mesma consulta após a alteração da suposição do esquema de chave.
Um wrapper injetando padrões — um ODM que preenche atributos que acredita pertencerem à chave pode preencher a chave inicial além do tamanho do esquema.

Como corrigir

LastEvaluatedKey de ida e volta 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 sem perdas se a chave cruzar um limite de requisição — quando o cursor de paginação vai para o navegador e volta, codifique o objeto LastEvaluatedKey inteiro (por exemplo, base64 do seu JSON) em vez de reconstruí-lo a partir dos 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 isso no KeyConditionExpression (sk > :x) em vez de um ExclusiveStartKey feito à mão.
Registre o LastEvaluatedKey cru quando falhar. Compare-o byte a byte com o que sua próxima requisição envia — camadas de serialização frequentemente renomeiam campos ou transformam números em strings.

Consulte no DynoTable

Pagine uma Query no DynoTable e inspecione o cursor LastEvaluatedKey cru entre as páginas — abra a tabela com ⌘K, rode uma Query e copie o token de paginação literalmente para o loop do seu SDK. O painel de consulta mostra exatamente quais atributos de chave o DynamoDB espera.

Use o Query Builder para gerar um programa de Query paginada com o tratamento correto de ExclusiveStartKey. Troque de perfil com ⌘P; Test Connection em Settings → Profiles. Veja Connect to AWS e Install.

Fontes

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

Erros relacionados

The provided key element does not match the schema — a mesma incompatibilidade de schema em uma chave de GetItem/escrita.
Condição da chave de consulta não suportada
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.