ValidationException: The provided key element does not match the schema

TL;DR — A chave que você passou não se alinha com o key schema declarado da tabela: nome de atributo errado, tipo errado (string vs número), ou uma chave de ordenação ausente. Faça a chave da requisição corresponder exatamente ao KeySchema + AttributeDefinitions.

O que significa

# what the engine actually returns, reproduced against DynamoDB Local — GetItem with pk passed as N where the schema declares S:
ValidationException: One or more parameter values were invalid: Type mismatch for key

Todo item do DynamoDB é endereçado por sua chave primária — uma chave de partição, opcionalmente mais uma chave de ordenação — com nomes e tipos fixos definidos na criação da tabela. GetItem, DeleteItem, UpdateItem e cada Key em um lote precisam fornecer exatamente essa chave: como a referência da API coloca, "for the primary key, you must provide all of the attributes." Este erro dispara quando a chave fornecida não corresponde. É um ValidationException (HTTP 400) e não retentável — a mesma requisição falha até que a chave seja corrigida.

Por que isso acontece

Nome de atributo errado — você passou id mas a chave da tabela é pk.
Tipo errado — a chave é definida como Número (N) mas você enviou uma String ("123"), ou vice-versa. "123" e 123 são chaves diferentes para o DynamoDB.
Faltar a chave de ordenação — a tabela tem uma chave composta mas seu Key só tem a chave de partição (ou uma chave de ordenação extra em uma tabela só-de-partição).
Atributos extras em Key — o map Key precisa conter apenas os atributos de chave, nada mais.

Como corrigir

Verifique o key schema da tabela (DescribeTable → KeySchema + AttributeDefinitions), depois faça o Key da requisição corresponder nome-por-nome e tipo-por-tipo. O painel de estatísticas da tabela do DynoTable mostra o mesmo key schema — chave de partição, chave de ordenação e seus tipos — num relance.
Corrija incompatibilidades de número/string. Se a chave é N, passe um número JS (o Document Client faz o marshal); com o cliente de baixo nível use {N: '123'}, não {S: '123'}.
Forneça a chave composta completa. Tabelas de chave composta precisam tanto da chave de partição quanto da de ordenação em toda chamada baseada em item.

Exemplo

// Table: Users, key = { pk (S) HASH, sk (S) RANGE }
import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, GetCommand} from '@aws-sdk/lib-dynamodb';

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));

//  both key parts, correct names/types
await doc.send(new GetCommand({TableName: 'Users', Key: {pk: 'USER#1', sk: 'PROFILE'}}));

//  missing sort key → "provided key element does not match the schema"
// await doc.send(new GetCommand({TableName: 'Users', Key: {pk: 'USER#1'}}));

FAQ

O que causa "The provided key element does not match the schema"? A chave na sua requisição não se alinha com o key schema declarado da tabela: um nome de atributo errado, um tipo errado (uma chave Número enviada como String ou vice-versa), uma chave de ordenação ausente em uma tabela de chave composta, ou atributos extras que não são chave no map Key.

Como verifico o key schema da minha tabela? Chame DescribeTable e leia KeySchema mais AttributeDefinitions, depois faça o Key da requisição corresponder nome-por-nome e tipo-por-tipo. Tabelas de chave composta precisam tanto da chave de partição quanto da de ordenação em toda chamada baseada em item.

Erros relacionados

Referências

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