ValidationException: The provided key element does not match the schema

In breve — La chiave che hai passato non si allinea con il key schema dichiarato della tabella: nome di attributo errato, tipo errato (stringa vs numero), o una sort key mancante. Fai corrispondere la chiave della richiesta esattamente a KeySchema + AttributeDefinitions.

Cosa 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

Ogni Item DynamoDB è indirizzato dalla sua chiave primaria — una partition key, opzionalmente più una sort key — con nomi e tipi fissi impostati alla creazione della tabella. GetItem, DeleteItem, UpdateItem e ogni Key in un batch devono fornire esattamente quella chiave: come dice l'API reference, "per la chiave primaria, devi fornire tutti gli attributi." Questo errore scatta quando la chiave fornita non corrisponde. È una ValidationException (HTTP 400) e non è ripetibile — la stessa richiesta fallisce finché la chiave non viene corretta.

Perché succede

Nome di attributo errato — hai passato id ma la chiave della tabella è pk.
Tipo errato — la chiave è definita come Number (N) ma hai inviato una String ("123"), o viceversa. "123" e 123 sono chiavi diverse per DynamoDB.
Sort key mancante — la tabella ha una chiave composita ma la tua Key ha solo la partition key (o una sort key in più su una tabella con sola partition key).
Attributi in più in Key — la mappa Key deve contenere solo gli attributi chiave, nient'altro.

Come risolverlo

Controlla il key schema della tabella (DescribeTable → KeySchema + AttributeDefinitions), poi fai corrispondere la Key della richiesta nome-per-nome e tipo-per-tipo. Il pannello Statistiche della tabella di DynoTable mostra lo stesso key schema — partition key, sort key e i loro tipi — a colpo d'occhio.
Correggi le mancate corrispondenze numero/stringa. Se la chiave è N, passa un numero JS (il Document Client lo marshalla); con il client di basso livello usa {N: '123'}, non {S: '123'}.
Fornisci la chiave composita completa. Le tabelle a chiave composita necessitano sia della partition sia della sort key in ogni chiamata basata su Item.

Esempio

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

Cosa causa "The provided key element does not match the schema"? La chiave nella tua richiesta non si allinea con il key schema dichiarato della tabella: un nome di attributo errato, un tipo errato (una chiave Number inviata come String o viceversa), una sort key mancante su una tabella a chiave composita, o attributi non-chiave in più nella mappa Key.

Come controllo il key schema della mia tabella? Chiama DescribeTable e leggi KeySchema più AttributeDefinitions, poi fai corrispondere la Key della richiesta nome-per-nome e tipo-per-tipo. Le tabelle a chiave composita necessitano sia della partition key sia della sort key in ogni chiamata basata su Item.

Errori correlati

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.