Query key condition not supported

TL;DR — Your KeyConditionExpression used an operator the key schema doesn't allow. The partition key supports only equality (=). The sort key supports =, <, <=, >, >=, BETWEEN, and begins_with() — but not contains(), <>, IN, or begins_with on the partition key. Move anything else to a FilterExpression.

What it means

ValidationException: Query key condition not supported

This ValidationException (HTTP 400) means the condition you put on a key isn't one DynamoDB can evaluate against the sorted key structure. Query walks a partition and scans its sort-key range, so key conditions are restricted to operations that map onto that structure. It's not retryable — rewrite the query.

Why it happens

• contains() on a key — contains() works only in a FilterExpression, never on a partition or sort key.
• A non-equality operator on the partition key — the partition key must use =. begins_with, <, >, BETWEEN, or <> on it are unsupported.
• IN or <> (not-equals) on a key — neither is a supported key operator; both belong in a filter.
• Referencing a non-key attribute in the KeyConditionExpression — only the table/index partition and sort keys are allowed there (that variant is Query condition missed key schema element).
• begins_with() on a Number sort key — begins_with works only on String or Binary sort keys, and the function name is case-sensitive (begins_with, not BEGINS_WITH).
• Querying a GSI/LSI whose key schema differs from the base table's, using the base table's keys by mistake.

How to fix it

1. Use = on the partition key, always. Query needs an exact partition key; you can't range-scan across partitions.
2. Restrict the sort key to supported operators — =, <, <=, >, >=, BETWEEN … AND …, or begins_with(sk, :prefix).
3. Move everything else to a FilterExpression — contains(), <>, IN, substring matches. (Filters run after the read and still consume capacity, so design keys for the common access pattern.)
4. Query the right index — if you need a different access pattern, add/query a GSI whose partition/sort keys match the condition you want, and pass its IndexName.
5. Only reference key attributes in the key condition; put non-key predicates in the filter.

FAQ

Why is "Query key condition not supported" thrown? The KeyConditionExpression used an operator the key schema can't evaluate — such as contains() on a key, or an inequality/begins_with on the partition key. Partition keys allow only equality; sort keys allow a limited set of comparisons. Anything else must move to a FilterExpression.

Can I use contains() in a DynamoDB Query? Only in a FilterExpression, not a KeyConditionExpression. contains() isn't a valid key operator. If you need substring matching as an access pattern, model it into a sort key you can begins_with() against, or use a GSI.

Reproduce it

A Query using begins_with on the partition key:

await client.send(
  new QueryCommand({
    TableName: 'orders',
    KeyConditionExpression: 'begins_with(pk, :p)',
    ExpressionAttributeValues: {':p': {S: 'ORDER#'}}
  })
);

Real output:

ValidationException: Query key condition not supported
HTTP 400

The partition key accepts equality and nothing else. begins_with, <, > and BETWEEN are legal on the sort key only — which is the real lesson behind this error, and why it usually means the access pattern needs a different key design rather than a different expression.

Related errors

• Query condition missed key schema element — a non-key attribute in the key condition, or a missing partition key.
• ValidationException (overview)
• Code example: Query in Node.js · in Python (boto3) — valid key conditions in working code.
• Learn: Key condition expressions · Query vs Scan · Indexes overview

References

• Query — Amazon DynamoDB API Reference
• Working with queries in 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.

Reproduced 2026-07-26 against DynamoDB Local 2.x with AWS SDK for JavaScript v3.1095.0 — the output above is verbatim.