ValidationException: el elemento de clave proporcionado no coincide con el esquema

TL;DR — La clave que pasaste no encaja con el esquema de clave declarado de la tabla: nombre de atributo incorrecto, tipo incorrecto (cadena vs número), o una clave de ordenación que falta. Haz que la clave de la solicitud coincida exactamente con KeySchema + AttributeDefinitions.

Qué 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

Cada Item de DynamoDB se direcciona por su clave primaria — una clave de partición, opcionalmente más una clave de ordenación — con nombres y tipos fijos establecidos en la creación de la tabla. GetItem, DeleteItem, UpdateItem y cada Key en un lote deben aportar exactamente esa clave: como dice la referencia de la API, "for the primary key, you must provide all of the attributes." Este error se dispara cuando la clave aportada no coincide. Es un ValidationException (HTTP 400) y no es reintentable — la misma solicitud falla hasta que se corrige la clave.

Por qué ocurre

Nombre de atributo incorrecto — pasaste id pero la clave de la tabla es pk.
Tipo incorrecto — la clave está definida como Number (N) pero enviaste una String ("123"), o viceversa. "123" y 123 son claves distintas para DynamoDB.
Falta la clave de ordenación — la tabla tiene una clave compuesta pero tu Key solo tiene la clave de partición (o una clave de ordenación extra en una tabla con solo clave de partición).
Atributos extra en Key — el mapa Key debe contener solo los atributos de clave, nada más.

Cómo solucionarlo

Comprueba el esquema de clave de la tabla (DescribeTable → KeySchema + AttributeDefinitions), luego haz que el Key de la solicitud coincida nombre por nombre y tipo por tipo. El panel de estadísticas de tabla de DynoTable muestra ese mismo esquema de claves — clave de partición, clave de ordenación y sus tipos — de un vistazo.
Corrige las discrepancias de número/cadena. Si la clave es N, pasa un número de JS (el Document Client lo marshalliza); con el cliente de bajo nivel usa {N: '123'}, no {S: '123'}.
Aporta la clave compuesta completa. Las tablas con clave compuesta necesitan tanto la clave de partición como la de ordenación en cada llamada basada en Items.

Ejemplo

// 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é causa "The provided key element does not match the schema"? La clave de tu solicitud no encaja con el esquema de clave declarado de la tabla: un nombre de atributo incorrecto, un tipo incorrecto (una clave Number enviada como String o viceversa), una clave de ordenación que falta en una tabla con clave compuesta, o atributos que no son clave de más en el mapa Key.

¿Cómo compruebo el esquema de clave de mi tabla? Llama a DescribeTable y lee KeySchema más AttributeDefinitions, luego haz que el Key de la solicitud coincida nombre por nombre y tipo por tipo. Las tablas con clave compuesta necesitan tanto la clave de partición como la de ordenación en cada llamada basada en Items.

Errores relacionados

Referencias

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.