ValidationException : The provided key element does not match the schema

TL;DR — La clé que tu as passée ne correspond pas au schéma de clé déclaré de la table : mauvais nom d'attribut, mauvais type (chaîne vs nombre), ou clé de tri manquante. Fais correspondre exactement la clé de la requête à KeySchema + AttributeDefinitions.

Ce que ça signifie

# 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

Chaque élément DynamoDB est adressé par sa clé primaire — une clé de partition, éventuellement plus une clé de tri — avec des noms et types fixés à la création de la table. GetItem, DeleteItem, UpdateItem et chaque Key d'un lot doivent fournir exactement cette clé : comme le dit la référence de l'API, « for the primary key, you must provide all of the attributes ». Cette erreur se déclenche quand la clé fournie ne correspond pas. C'est une ValidationException (HTTP 400) et non réessayable — la même requête échoue tant que la clé n'est pas corrigée.

Pourquoi ça arrive

Mauvais nom d'attribut — tu as passé id mais la clé de la table est pk.
Mauvais type — la clé est définie comme Number (N) mais tu as envoyé une String ("123"), ou inversement. "123" et 123 sont des clés différentes pour DynamoDB.
Clé de tri manquante — la table a une clé composite mais ton Key n'a que la clé de partition (ou une clé de tri en trop sur une table à clé de partition seule).
Attributs en trop dans Key — la map Key ne doit contenir que les attributs de clé, rien d'autre.

Comment le corriger

Vérifie le schéma de clé de la table (DescribeTable → KeySchema + AttributeDefinitions), puis fais correspondre le Key de la requête nom pour nom et type pour type. Le panneau de statistiques de table de DynoTable montre le même schéma de clé — clé de partition, clé de tri et leurs types — d'un coup d'œil.
Corrige les non-concordances nombre/chaîne. Si la clé est N, passe un nombre JS (le Document Client le marshalle) ; avec le client bas niveau, utilise {N: '123'}, pas {S: '123'}.
Fournis la clé composite complète. Les tables à clé composite ont besoin à la fois de la clé de partition et de la clé de tri sur chaque appel basé sur un élément.

Exemple

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

Qu'est-ce qui cause « The provided key element does not match the schema » ? La clé de ta requête ne correspond pas au schéma de clé déclaré de la table : un mauvais nom d'attribut, un mauvais type (une clé Number envoyée comme String ou inversement), une clé de tri manquante sur une table à clé composite, ou des attributs non clé en trop dans la map Key.

Comment vérifier le schéma de clé de ma table ? Appelle DescribeTable et lis KeySchema plus AttributeDefinitions, puis fais correspondre le Key de la requête nom pour nom et type pour type. Les tables à clé composite ont besoin à la fois de la clé de partition et de la clé de tri sur chaque appel basé sur un élément.

Erreurs liées

Références

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.