Common DynamoDB Errors (and How to Fix Them)

A ValidationException means DynamoDB rejected your request before running it because a parameter was malformed. Here are the common triggers and the exact fix for each.

This ValidationException means your KeyConditionExpression didn't include the partition key, or referenced an attribute that isn't part of the table/index key. Here's the fix.

This ValidationException means a key attribute's name or type doesn't match your table definition — wrong key name, a missing sort key, or a number sent as a string. Here's the fix.

The most common cause is a reserved keyword used raw, or a missing #name / :value placeholder in your UpdateExpression. Here's how to read the message and fix it.

This ValidationException means a value in ExpressionAttributeValues is empty, the wrong type, or references a placeholder you never defined. Here's the fix.

DynamoDB items are capped at 400 KB. This ValidationException means your item (or the item after an update) is over the limit. Here's how to check the size and fix it.

A ConditionalCheckFailedException means your write's ConditionExpression evaluated to false, so DynamoDB rejected it and left the item unchanged. Usually it's expected — here's how to handle it.

A TransactionCanceledException means one item in your transaction failed, so the whole transaction rolled back. The fix is to read the CancellationReasons array. Here's how.

This error means you're reading or writing faster than the table's provisioned capacity allows. Switch to on-demand, raise capacity/auto-scaling, keep backoff retries, and fix hot partitions.

A ThrottlingException means your request rate exceeded a limit — often control-plane API calls or account-level limits. Retry with exponential backoff and reduce call frequency.

This error only happens on tables with a Local Secondary Index — an item collection (all items sharing one partition key) exceeded 10 GB. Here's how to fix it.

This error means the table or index you're addressing doesn't exist in the region/account you're calling. Usually it's a wrong table name, wrong region, or the wrong credentials.

This error means you tried to create/delete/modify a table that already exists or is mid-operation (CREATING, UPDATING, DELETING). Check the table's status before acting.

An AccessDeniedException means your IAM identity lacks permission for the DynamoDB action (or the resource/condition doesn't match). The message names the exact action and resource — here's how to fix the policy.

The AWS SDK couldn't determine which region to send DynamoDB requests to. Set the region on the client, via AWS_REGION, or in your AWS config. Here's each option.

This UnrecognizedClientException means your AWS credentials are wrong, expired, or not being picked up. Here's how to track down which and fix it.

DynamoDB Local failed to launch — usually a missing/incompatible Java runtime, a port already in use, or a bad install path. Here's how to fix each.

Your client got connection refused talking to DynamoDB Local — usually the emulator isn't running, the endpoint/port is wrong, or the SDK is hitting real AWS instead of localhost. Here's the fix.