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).
• BETWEEN where the sort key doesn't support the comparison — check the sort key exists and is a comparable scalar type.
• 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.

Related errors

• Query condition missed key schema element — a non-key attribute in the key condition, or a missing partition key.
• ValidationException (overview)
• Learn: Key condition expressions · Query vs Scan