How do I troubleshoot the "provided key element does not match the schema" error in DynamoDB?

Short description

This error can occur for the following reasons:

• You specified the incorrect data type for the key.
• You incorrectly named attributes.
• You specified only part of a key.
• The data is writing to the wrong table.
• There's an unnecessary additional key.
• You run a GetItem request to try to get a range of items instead of a single item.
• Your table has a composite primary key, so you run a GetItem request and don't specify the partition key and sort key.
• Your table doesn't have a sort key, so you run a GetItem request and specify only a partition key.

Resolution

Review your primary key and sort key data type

For your GetItem command to succeed, the primary and sort key data must be the same data type as the data for your DynamoDB table. In the following example command, the sort key Year has a string (S) data type:

aws dynamodb get-item --table-name Key-Element --key '{"EventID":{"S":"test-item01"}, "Year":{"S":"2024"}}'

Because the table uses a number (N) data type, you get the following error message:

"An error occurred (ValidationException) when calling the GetItem operation: The provided key element does not match the schema"

Instead, run the following command that uses the number data type:

aws dynamodb get-item --table-name Key-Element --key '{"EventID":{"S":"test-item01"}, "Year":{"N":"2024"}}'

You get an output similar to the following:

{
    "Item": {
        "EventID": {
            "S": "test-item01"
        },
        "Year": {
            "N": "2024"
        },
        "Works?": {
            "N": "1"
        }
    }
}

Choose an operation for your use case

Use the BatchGetItem or GetItem operation

When you retrieve data from your DynamoDB tables, you can use either the Getitem or BatchGetitem operations. The GetItem operation retrieves one record at a time. The request must include the table's key schema.

The BatchGetItem operation requires that you provide the partition key for tables that have only a partition key. For tables that have a composite primary key, you must provide the partition and sort key when you use BatchGetItem.

Use the Query operation

To retrieve data when you don't specify a sort key, use the Query operation. Because Query lets you to specify only the partition key when you retrieve data, use this operation for tables with a composite primary key.

Use the DynamoDB Scan API

To search for data based on a non-key attribute, use the DynamoDB Scan API. The Scan operation lets you use a FilterExpression to filter data based on any attribute without the need to specify the primary key.

To use a non-key attribute to search for data, use a nested search within FilterExpression. For example, to search for items that have a userId attribute in the nested Data attribute that matches a specific value, use the following expression:

"Data.userId": your_expression_values."

Important: Because the Scan operation iterates over all items to check if the filter condition is met, the operation can quickly incur charges. If you must use the Scan operation, then add pagination when you scan large tables. The Scan API returns only up to 1 MB of data per call. Use pagination to scan only new data.