Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

DynamoDB Query rejects your key condition expression

ErrorQuery condition missed key schema element

Short answer

Query needs an equality test on the partition key of the table or index you query. The error means your KeyConditionExpression names a non-key attribute, leaves the partition key out, or targets an index without IndexName. Put the key in the condition, move other tests to a filter, and name the index.

  • Applies to Amazon DynamoDB, AWS CLI v2, AWS SDK for JavaScript v3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the real key schema of the table, with its indexes, and compare the attribute names in your condition with it.

    aws dynamodb describe-table --table-name Orders --query 'Table.{keys:KeySchema,gsi:GlobalSecondaryIndexes[].{name:IndexName,keys:KeySchema}}'
  2. 2Match what you see, then jump to its fix

    1. 1Your KeyConditionExpression is something like status = :s, where status is not the partition or sort keyThe condition tests an attribute that is not part of the keyFix
    2. 2Only the sort key is in the condition, or the partition key uses <, >, begins_with or BETWEENThe partition key is missing, or is not an equality testFix
    3. 3The attribute in your condition is the key of a global or local secondary index, and the call has no IndexNameYou query by the keys of a secondary index but did not name the indexFix

What does the error look like?

  • Query condition missed key schema element
  • ValidationException returned by the Query call

Cause 1 of 3

The condition tests an attribute that is not part of the key

1Check

A key condition may only use key attributes: an equality on the partition key, and optionally one comparison on the sort key.

aws dynamodb describe-table --table-name Orders --query 'Table.KeySchema'

2Fix

Put the partition key in KeyConditionExpression. Move every non-key test into FilterExpression, which cannot hold key attributes. If you need to look items up by that non-key attribute often, add a secondary index keyed on it.

aws dynamodb query \
    --table-name Orders \
    --key-condition-expression "customerId = :c" \
    --filter-expression "#s = :s" \
    --expression-attribute-names '{"#s":"status"}' \
    --expression-attribute-values '{":c":{"S":"c-100"},":s":{"S":"open"}}'

3Verify

The call returns an Items list instead of a ValidationException.

# check the Count field in the output

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 3

The partition key is missing, or is not an equality test

1Check

Query reads one partition. The partition key must be compared with = to a single value; a sort key condition can then be added with AND.

aws dynamodb describe-table --table-name Orders --query 'Table.KeySchema'

2Fix

Add the partition key equality first, then the sort key condition. To read across many partitions you need a scan or a different index design.

aws dynamodb query \
    --table-name Orders \
    --key-condition-expression "customerId = :c AND orderDate BETWEEN :a AND :b" \
    --expression-attribute-values '{":c":{"S":"c-100"},":a":{"S":"2026-01-01"},":b":{"S":"2026-06-30"}}'

3Verify

The query returns items for that one partition.

# check the Count and ScannedCount fields

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 3 of 3

You query by the keys of a secondary index but did not name the index

1Check

Without IndexName, Query uses the table's own key schema, so the index keys do not count. Compare the attribute with the index list from the first step.

aws dynamodb describe-table --table-name Orders --query 'Table.GlobalSecondaryIndexes[].IndexName'

2Fix

Add the index name to the query. Remember that a global secondary index returns only the attributes projected into it, and does not support strongly consistent reads.

aws dynamodb query \
    --table-name Orders \
    --index-name status-index \
    --key-condition-expression "#s = :s" \
    --expression-attribute-names '{"#s":"status"}' \
    --expression-attribute-values '{":s":{"S":"open"}}'

3Verify

The query returns items from the index.

# check the Count field in the output

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Write down the access patterns (which attribute you look items up by) before you design keys and indexes.
  • Wrap queries in one data-access function per pattern, so each has a single tested key condition.
  • Use expression attribute names for any attribute that might be a DynamoDB reserved word.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

The AWS SDK in Node.js cannot find any credentials

Missing credentials in config, if using AWS_CONFIG_FILE, set AWS_SDK_LOAD_CONFIG=1

The AWS SDK walks a fixed credential chain: code, environment variables, the shared files in ~/.aws, then role sources such as ECS or EC2.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.