ValidationException: Query condition missed key schema element
TL;DR — Your KeyConditionExpression must include an equality (=) on the partition key. If you're querying by a non-key attribute, you need a Query on a GSI/LSI that has that attribute as its key — or a Scan with a FilterExpression.
What it means
The full message is usually:
ValidationException: Query condition missed key schema element: <attributeName>Query only works against a key. DynamoDB is telling you the KeyConditionExpression either omits the partition key entirely, or names an attribute that isn't the partition/sort key of the table (or of the index you're querying).
Why it happens
- The
KeyConditionExpressionfilters on a regular attribute (e.g.email,status) instead of the partition key. - You're querying the base table but the attribute is only a key on a GSI — you forgot
IndexName. - The partition key is present but with an operator other than
=(the partition key must be an exact match; only the sort key supports<,>,begins_with,between). - A typo in the attribute name so it no longer matches the schema.
How to fix it
- Query on the partition key with
=. Every Query needspk = :pk(using your table's real key name). - Need to query by a non-key attribute? Create a GSI with that attribute as its partition key and pass
IndexName. - Only need occasional access? Use
Scanwith aFilterExpressioninstead ofQuery— but note Scan reads the whole table.
Example
import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, QueryCommand} from '@aws-sdk/lib-dynamodb';
const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}));
// Query the base table by its partition key:
await doc.send(
new QueryCommand({
TableName: 'Orders',
KeyConditionExpression: 'pk = :pk',
ExpressionAttributeValues: {':pk': 'USER#123'}
})
);
// Query by a non-key attribute → use a GSI that keys on it:
await doc.send(
new QueryCommand({
TableName: 'Orders',
IndexName: 'byStatus',
KeyConditionExpression: 'status = :s',
ExpressionAttributeValues: {':s': 'SHIPPED'}
})
);