ValidationException: The provided key element does not match the schema

TL;DR — Der übergebene Key passt nicht zum deklarierten Key-Schema der Tabelle: falscher Attributname, falscher Typ (String vs. Zahl) oder ein fehlender Sort Key. Bring den Key der Anfrage exakt mit KeySchema + AttributeDefinitions in Einklang.

Was es bedeutet

# 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

Jedes DynamoDB-Item wird über seinen Primärschlüssel adressiert — einen Partition Key, optional plus einen Sort Key — mit festen Namen und Typen, die bei der Tabellenerstellung gesetzt werden. GetItem, DeleteItem, UpdateItem und jeder Key in einem Batch müssen genau diesen Key liefern: wie die API-Referenz es formuliert, "for the primary key, you must provide all of the attributes." Dieser Fehler tritt auf, wenn der gelieferte Key nicht passt. Es ist eine ValidationException (HTTP 400) und nicht wiederholbar — dieselbe Anfrage schlägt fehl, bis der Key korrigiert ist.

Warum es passiert

Falscher Attributname — du hast id übergeben, aber der Key der Tabelle ist pk.
Falscher Typ — der Key ist als Number (N) definiert, aber du hast einen String ("123") gesendet, oder umgekehrt. "123" und 123 sind für DynamoDB verschiedene Keys.
Fehlender Sort Key — die Tabelle hat einen zusammengesetzten Key, aber dein Key hat nur den Partition Key (oder einen zusätzlichen Sort Key bei einer Partition-only-Tabelle).
Zusätzliche Attribute in Key — die Key-Map darf nur die Key-Attribute enthalten, sonst nichts.

So behebst du es

Prüfe das Key-Schema der Tabelle (DescribeTable → KeySchema + AttributeDefinitions), und bring dann den Key der Anfrage Name für Name und Typ für Typ in Einklang. DynoTables Tabellen-Statistik-Panel zeigt dasselbe Key-Schema — Partition Key, Sort Key und ihre Typen — auf einen Blick.
Behebe Zahl-/String-Missverhältnisse. Ist der Key N, übergib eine JS-Zahl (der Document Client marshallt sie); mit dem Low-Level-Client verwende {N: '123'}, nicht {S: '123'}.
Liefere den vollständigen zusammengesetzten Key. Tabellen mit zusammengesetztem Key brauchen bei jedem item-basierten Aufruf sowohl Partition- als auch Sort Key.

Beispiel

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

Was verursacht "The provided key element does not match the schema"? Der Key in deiner Anfrage passt nicht zum deklarierten Key-Schema der Tabelle: ein falscher Attributname, ein falscher Typ (ein Number-Key als String gesendet oder umgekehrt), ein fehlender Sort Key bei einer Tabelle mit zusammengesetztem Key oder zusätzliche Nicht-Key-Attribute in der Key-Map.

Wie prüfe ich das Key-Schema meiner Tabelle? Rufe DescribeTable auf und lies KeySchema plus AttributeDefinitions, und bring dann den Key der Anfrage Name für Name und Typ für Typ in Einklang. Tabellen mit zusammengesetztem Key brauchen bei jedem item-basierten Aufruf sowohl den Partition Key als auch den Sort Key.

Referenzen

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.