ValidationException: The provided key element does not match the schema

TL;DR — The key you passed doesn't line up with the table's declared key schema: wrong attribute name, wrong type (string vs number), or a missing sort key. Match the request's key exactly to KeySchema + AttributeDefinitions.

What it means

# 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

Every DynamoDB item is addressed by its primary key — a partition key, optionally plus a sort key — with fixed names and types set at table creation. GetItem, DeleteItem, UpdateItem and each Key in a batch must supply exactly that key: as the API reference puts it, "for the primary key, you must provide all of the attributes." This error fires when the supplied key doesn't match. It's a ValidationException (HTTP 400) and not retryable — the same request fails until the key is corrected.

Why it happens

• Wrong attribute name — you passed id but the table's key is pk.
• Wrong type — the key is defined as Number (N) but you sent a String ("123"), or vice-versa. "123" and 123 are different keys to DynamoDB.
• Missing the sort key — the table has a composite key but your Key only has the partition key (or an extra sort key on a partition-only table).
• Extra attributes in Key — the Key map must contain only the key attributes, nothing else.

How to fix it

1. Check the table's key schema (DescribeTable → KeySchema + AttributeDefinitions), then make the request's Key match name-for-name and type-for-type. DynoTable's table stats panel shows the same key schema — partition key, sort key, and their types — at a glance.
2. Fix number/string mismatches. If the key is N, pass a JS number (the Document Client marshals it); with the low-level client use {N: '123'}, not {S: '123'}.
3. Supply the full composite key. Composite-key tables need both partition and sort key on every item-based call.

Example

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

What causes "The provided key element does not match the schema"? The key in your request doesn't line up with the table's declared key schema: a wrong attribute name, a wrong type (a Number key sent as a String or vice-versa), a missing sort key on a composite-key table, or extra non-key attributes in the Key map.

How do I check my table's key schema? Call DescribeTable and read KeySchema plus AttributeDefinitions, then make the request's Key match name-for-name and type-for-type. Composite-key tables need both the partition key and the sort key on every item-based call.

Related errors

• Query condition missed key schema element
• ValidationException (overview)
• Learn: DynamoDB data types · Composite primary keys

References

• GetItem — Amazon DynamoDB API Reference
• Core components of Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.