DynamoDB ValidationException: Key Does Not Match Schema

This error stops a lot of first DynamoDB requests cold:

ValidationException: The provided key element does not match the schema

You may also see the closely related variants:

ValidationException: One or more parameter values were invalid: Missing the key <name> in the item
ValidationException: The number of conditions on the keys is invalid

All of them mean the same thing: the key you sent doesn’t match the table’s primary key definition. DynamoDB validates the shape of your key before it does any work, and it’s strict — one wrong field and the whole request is rejected.

First, know your table’s key schema

Every fix starts here. Look up exactly what the table expects:

aws dynamodb describe-table --table-name Orders \
  --query "Table.{Keys:KeySchema,Attrs:AttributeDefinitions}"

That tells you the partition key, the sort key (if any), and the type of each (S, N, or B). Your request must provide exactly those attributes — no more, no fewer — with matching types. See Primary keys for how partition and sort keys work.

Cause 1: Missing the sort key

On a table with a composite primary key (partition + sort), GetItem, PutItem, UpdateItem and DeleteItem all require both key attributes. Sending only the partition key triggers the error:

// Table key schema: pk (partition) + sk (sort)
await client.send(new GetItemCommand({
  TableName: "Orders",
  Key: { pk: { S: "USER#42" } }          // ❌ sk is missing
}));

await client.send(new GetItemCommand({
  TableName: "Orders",
  Key: { pk: { S: "USER#42" }, sk: { S: "ORDER#1001" } }  // ✅ both keys
}));

If you only have the partition key and want every item under it, that’s a Query, not a GetItem:

new QueryCommand({
  TableName: "Orders",
  KeyConditionExpression: "pk = :pk",
  ExpressionAttributeValues: { ":pk": { S: "USER#42" } }
});

Cause 2: Wrong attribute name

Key attribute names are exact and case-sensitive. If the table’s partition key is pk but you send PK, id, or userId, it won’t match — even if the value is correct.

Key: { PK: { S: "USER#42" }, sk: { S: "ORDER#1001" } }  // ❌ "PK" ≠ "pk"

Copy the names straight from describe-table rather than from memory.

Cause 3: Wrong data type

The value’s type has to match the attribute definition. A key defined as Number (N) must receive a number, not a string:

// Table defines id as N
Key: { id: { S: "42" } }   // ❌ sent as String
Key: { id: { N: "42" } }   // ✅ sent as Number (note: N values are strings in wire format, but typed N)

This one hides easily when ids arrive from JSON, query params, or a language that stringifies numbers. If you use the Document Client / higher-level mappers, make sure the runtime value is a JS number, not a "string".

Cause 4: Extra attributes in the Key

The Key map may contain only the primary key attributes. Including a non-key attribute (say status or email) to “narrow” the lookup is invalid — you’ll get the schema-mismatch error. Filter on non-key attributes with a FilterExpression on a Query, or a ConditionExpression on a write, not by stuffing them into Key.

Cause 5: Querying with the wrong key condition

On Query, the KeyConditionExpression must reference the partition key with equality (pk = :pk) and, optionally, the sort key with a supported comparison. Referencing a non-key attribute, or using a range operator on the partition key, produces validation errors in the same family.

Diagnostic checklist

1. Run describe-table — note the exact key names, order, and types.
2. Composite key? Ensure you send both partition and sort key on single-item ops.
3. Match names exactly (case-sensitive).
4. Match types — a Number key needs a number, not a quoted string.
5. Put only key attributes in Key; move everything else to a filter/condition.
6. Only have the partition key? Switch from GetItem to Query.

Stop guessing the schema

Half of these bugs come from not having the table’s key schema in front of you while you write the request. Tablyne shows each table’s partition key, sort key and their types right in the UI, and lets you build correct queries visually — so a key mismatch is obvious before you ever run the call. Download Tablyne free to model and query your tables without second-guessing the schema.