DynamoDB Errors

Common DynamoDB Errors (and How to Fix Them)

The DynamoDB errors developers hit most — each with what it means, why it happens, and the exact fix.

Validation & expression errors (52)

DynamoDB ValidationException — Causes & How to Fix

A DynamoDB ValidationException means the request was rejected as malformed before it ran. The common triggers, the message to read, and each fix.

"Query condition missed key schema element" — DynamoDB Fix

Query condition missed key schema element means your KeyConditionExpression lacks an equality on the partition key. Query a GSI or Scan instead.

"The provided key element does not match the schema" — DynamoDB Fix

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

"Invalid UpdateExpression" Syntax Error — DynamoDB Fix

An Invalid UpdateExpression is usually a reserved keyword used raw, or a missing #name or :value placeholder. Alias reserved names with ExpressionAttributeNames and bind values with ExpressionAttributeValues.

"ExpressionAttributeValues contains invalid value" — DynamoDB Fix

This ValidationException means a value in ExpressionAttributeValues is empty, the wrong type, or a placeholder your expression never defined.

"Item size has exceeded the maximum allowed size" — DynamoDB Fix

DynamoDB items are capped at 400 KB. This ValidationException means your item is over the limit. Measure it and split or trim attributes.

DynamoDB ConditionalCheckFailedException — Causes & Fix

ConditionalCheckFailedException means your ConditionExpression evaluated to false, so DynamoDB rejected the write and left the item unchanged.

DynamoDB TransactionCanceledException — Decode the Cancellation Reasons

TransactionCanceledException means one item failed and the whole transaction rolled back. Read the CancellationReasons array to find which item and why.

DynamoDB SerializationException — Causes & Fix

SerializationException means your JSON doesn't match DynamoDB's wire format — usually a number wrapped as a string. Fix the typed AttributeValue wrappers.

"Supplied AttributeValue is empty" — DynamoDB Fix

This ValidationException means an AttributeValue holds no typed value — an empty set, an empty key string, or an undefined field. Drop it or set a value.

"One or more parameter values were invalid" — DynamoDB Fix

This ValidationException means one value breaks a DynamoDB rule — an empty set, an empty key string, or a type mismatch. The message names the parameter.

"Invalid size for parameter" — DynamoDB Vector Write Fix

DynamoDB rejects a vector write when the embedding's dimension count doesn't match the vector index. The message names the attribute and both sizes.

"Search vector contains invalid values" — DynamoDB Fix

SearchVectors rejects a query vector wrapped in DynamoDB's L type or carrying non-float values. The parameter is a bare JSON array, not a List attribute.

"SearchConditionExpression must be provided" — DynamoDB Fix

A vector index with a HASH search-schema key requires every SearchVectors call to pin exactly one partition value. The filter stopped being optional at index creation.

"Query key condition not supported" — DynamoDB Fix

DynamoDB rejects a KeyConditionExpression that uses an operator the key schema forbids — partition keys take only equality. Here are the allowed ones.

"Attribute name is a reserved keyword" — DynamoDB Fix

DynamoDB rejects reserved words like status, name or size as raw attribute names. Alias it with an ExpressionAttributeNames placeholder like #status.

"Float types are not supported" — DynamoDB boto3 Fix

boto3 raises TypeError "Float types are not supported" because DynamoDB stores exact decimals. Convert floats to decimal.Decimal via the string form.

"Number overflow" — DynamoDB Number Size Limit Fix

DynamoDB's N type holds 38 digits of precision and a magnitude up to ~9.9E+125. Past that, store large IDs and high-precision values as strings instead.

"The provided expression refers to an attribute that does not exist" — Fix

Your UpdateExpression or ConditionExpression references a path that isn't on the item — a missing parent map, a typo, or math on a missing attribute.

"Provided list of item keys contains duplicates" (BatchGetItem) — Fix

DynamoDB rejects a BatchGetItem when the Keys list for a table repeats a primary key. The whole batch fails, so de-duplicate the keys before sending.

"Provided list of item keys contains duplicates" (BatchWriteItem) — Fix

DynamoDB rejects a BatchWriteItem when two actions target the same primary key. A batch cannot touch one item twice, so collapse the duplicates.

"Expression size has exceeded the maximum allowed size" (4 KB) — Fix

DynamoDB caps every expression string at 4 KB. A FilterExpression, ConditionExpression, or UpdateExpression past that is rejected. How to shrink it.

"Aggregated size of all range keys has exceeded the size limit" — Fix

DynamoDB caps a sort key at 1024 bytes and a partition key at 2048 bytes. Shrink key attribute values or hash long identifiers before storing them.

"Filter Expression can only contain non-primary key attributes" — Fix

DynamoDB rejects a FilterExpression that names a partition or sort key. Keys belong in the KeyConditionExpression; move them out of the filter.

DynamoDB BatchGetItem 100-Item Limit — "Too Many Items" Fix

BatchGetItem accepts at most 100 items (and 16 MB) per call. Ask for more and DynamoDB rejects the whole request. The limit, plus the chunking loop.

"Too many items requested for the BatchWriteItem call" — Fix

BatchWriteItem accepts at most 25 put or delete actions per call. Send more and DynamoDB rejects the whole request with a ValidationException.

DynamoDB "Can Not Use Both Expression and Non-Expression Parameters" — Fix

DynamoDB rejects a request that mixes a legacy parameter like KeyConditions with KeyConditionExpression. Drop the legacy parameter and use expressions.

"Local secondary indexes must be specified at table creation" — Fix

A local secondary index can only be defined when the table is created, never added later. Why the constraint exists and how to work around it.

DynamoDB TransactionCanceledException — ConditionalCheckFailed Fix

A TransactWriteItems canceled with ConditionalCheckFailed means one item's condition failed and rolled back the whole transaction. How to find it.

"Value provided in ExpressionAttributeNames unused in expressions" — Fix

DynamoDB rejects a request that declares an ExpressionAttributeNames alias no expression references. Remove it, or fix the expression that missed it.

"Value provided in ExpressionAttributeValues unused in expressions" — Fix

DynamoDB rejects a request that declares an ExpressionAttributeValues placeholder no expression uses. Remove the orphan value or fix the expression.

DynamoDB S3 Import Failed — Invalid Format Fix

DynamoDB Import from S3 fails when objects don't match the declared InputFormat or compression, or when items lack the primary key.

"Size of hashkey has exceeded the maximum size limit of 2048 bytes" — Fix

A DynamoDB partition key can be at most 2048 bytes and a sort key 1024 bytes. Exceed either and the write is rejected. Shorten or hash the key value.

DynamoDB GSI "Does Not Project" Attribute — Fix

A GSI returns only key attributes plus its projection, so querying it for anything else fails. Change the projection or stop requesting attributes the index does not store.

"Nesting Levels have exceeded supported limits" — DynamoDB 32-Level Fix

DynamoDB caps map and list nesting at 32 levels — deeper documents throw "Nesting Levels have exceeded supported limits". Flatten nested maps and lists below 32 levels.

"Segment must be less than TotalSegments" — Parallel Scan Fix

Parallel Scan requires 0 ≤ Segment < TotalSegments, and both must be sent together. Give each worker a distinct Segment from 0 to TotalSegments − 1.

DynamoDB "Cannot Specify AttributesToGet When Select Is COUNT" — Fix

DynamoDB rejects a Query or Scan that sets Select=COUNT with a ProjectionExpression or AttributesToGet. COUNT returns a number, so drop the projection.

DynamoDB Streams "The ARN provided is invalid" — Fix

DynamoDB Streams rejects a malformed or placeholder stream ARN like /stream/latest. Pass the real LatestStreamArn that DescribeTable returns, verbatim.

"Transaction request cannot include multiple operations on one item" — Fix

DynamoDB rejects a TransactWriteItems call when two actions target the same primary key. Collapse the duplicates, or move one to a separate write.

DynamoDB TransactWriteItems 100-Action Limit — Fix

TransactWriteItems caps at 100 actions; past that you get a ValidationException on TransactItems length. Split it, or use BatchWriteItem at 25 per call.

DynamoDB TTL Attribute Must Be a Number — Causes & Fix

DynamoDB TTL only expires items whose TTL attribute is a Number in Unix epoch seconds. A String, a millisecond value, or a missing attribute never expires.

DynamoDB "The expression can not be empty" — Fix

DynamoDB rejects an expression parameter passed as an empty string. Omit FilterExpression or UpdateExpression entirely when you have nothing to send.

"ExpressionAttributeNames contains invalid key: Syntax error" — Fix

DynamoDB rejects an ExpressionAttributeNames map whose placeholder key breaks the `#name` syntax. The naming rule, and where the real name belongs.

"Two document paths overlap with each other" (DynamoDB) — Fix

DynamoDB rejects an UpdateExpression that sets both a parent path and a path nested inside it. Fold the child into the parent, or split into two updates.

"The document path provided in the update expression is invalid" — Fix

An invalid document path means the parent of your nested attribute does not exist or is not a map. DynamoDB never auto-creates it, so create it first.

"An operand in the update expression has an incorrect data type" — Fix

The update operand's type doesn't match what's stored — ADD on a non-number, list_append on a non-list, a mismatched set.

DynamoDB IdempotentParameterMismatchException — Causes & Fix

TransactWriteItems rejects a retry that reuses a ClientRequestToken with a different payload inside the 10-minute idempotency window..

"Consistent reads are not supported on global secondary indexes" — Fix

Querying a GSI with ConsistentRead true throws a ValidationException. GSIs serve eventually consistent reads only. Drop the flag or read the base table.

DynamoDB DuplicateItemException (PartiQL INSERT) — Causes & Fix

PartiQL INSERT fails with DuplicateItemException when the primary key already exists. Unlike PutItem it never overwrites, so use UPDATE or PutItem.

"Unexpected from source" (DynamoDB PartiQL) — Fix

PartiQL throws "Unexpected from source" when a table name with dashes or other special characters is not double-quoted in FROM. One quote pair fixes it.

boto3 "Parameter validation failed" (ParamValidationError) — Fix

botocore raises ParamValidationError before the request reaches DynamoDB — usually a client-vs-resource type mixup.. Check client vs resource argument types before the call leaves botocore.

"The provided starting key is invalid" (DynamoDB) — Fix

DynamoDB rejects an ExclusiveStartKey that doesn't match the key schema of the table or index you're paginating. Pass LastEvaluatedKey back verbatim.

Throughput & throttling errors (11)

DynamoDB ProvisionedThroughputExceededException — Causes & Fix

DynamoDB throws ProvisionedThroughputExceededException when reads or writes pass a table or GSI's provisioned capacity.. Check table and GSI consumed capacity, then raise provisioned limits or switch hot keys.

DynamoDB ThrottlingException — Causes & Fix

ThrottlingException means your request rate passed a limit, often on control-plane calls like CreateTable. Retry with exponential backoff and slow down.

DynamoDB ItemCollectionSizeLimitExceededException — Causes & Fix

This error only hits tables with a Local Secondary Index — an item collection (all items sharing one partition key) passed 10 GB.

DynamoDB RequestLimitExceeded — Causes & Fix

RequestLimitExceeded is an account-level rate limit — on-demand defaults to 40,000 read and write request units per second. Raise it in Service Quotas.

DynamoDB TransactionConflictException — Causes & Fix

TransactionConflictException means another transaction is already touching the same item. It's transient — retry with backoff and keep transactions small.

"Provisioned throughput decreases are limited within a given day" — Fix

DynamoDB caps how many times you can lower a table's provisioned capacity per UTC day.. Wait for the UTC-day quota to reset, or use on-demand / a new table.

DynamoDB On-Demand Throughput Exceeded — Causes & Fix

On-demand tables still throttle — a configured max throughput, a ramp past double your previous peak, or a table quota.. Raise on-demand max throughput or the table quota.

DynamoDB Throttled Despite Capacity — Hot Partition Fix

DynamoDB throttles one hot partition key even with spare table capacity, because each physical partition caps at 3,000 RCU and 1,000 WCU.

DynamoDB TransactionInProgressException — Causes & Fix

A TransactWriteItems retry reused the ClientRequestToken of an attempt still running. Keep retrying with backoff and tune timeouts past 5 seconds.

DynamoDB InternalServerError (HTTP 500) — What to Do

An HTTP 500 from DynamoDB is a transient service-side fault, safe to retry — but a failed write may still have been applied. Retry with backoff; confirm the write before assuming failure.

DynamoDB ReplicatedWriteConflictException — Causes & Fix

On a multi-Region strongly consistent global table, a write is rejected when another Region is modifying the same item. It's retryable with backoff once the conflicting Region write settles.

Table & resource errors (19)

DynamoDB ResourceNotFoundException — Causes & Fix

ResourceNotFoundException means the table or index doesn't exist in the region and account you're calling. Check the name, region, and credentials.

DynamoDB ResourceInUseException ("Table already exists") — Fix

ResourceInUseException means the table already exists or is still CREATING, UPDATING or DELETING. Check its status with DescribeTable before you act.

DynamoDB LimitExceededException — Causes & Fix

LimitExceededException means too many concurrent CreateTable, UpdateTable or DeleteTable calls, or a hit account limit. Serialize control-plane calls and stay under account quotas.

"The table does not have the specified index" — Fix

DynamoDB rejects the call because the IndexName doesn't exist on that table, is misspelled, or the GSI isn't ACTIVE yet. Confirm IndexName on the table and that the GSI is ACTIVE.

DynamoDB BackupNotFoundException — Causes & Fix

DynamoDB BackupNotFoundException means no backup matches the BackupArn you passed. Usually a wrong ARN, a deleted or expired backup, or the wrong region.

DynamoDB ReplicaNotFoundException — Causes & Fix

ReplicaNotFoundException means the Region replica you're updating is not in the global table — a wrong Region, a removed replica, or a race.

"Attempting to modify a GSI that is being created" — Fix

DynamoDB blocks structural changes while a global secondary index is still building. Wait for IndexStatus to reach ACTIVE, or sequence your changes.

DynamoDB ExportTableToPointInTime — PITR Not Enabled Fix

ExportTableToPointInTime requires point-in-time recovery on the source table, or it throws PointInTimeRecoveryUnavailableException. The one-command fix.

DynamoDB Global Table Version Mismatch — Causes & Fix

Global table creation fails when replicas don't line up — non-empty tables, mismatched key schemas or GSIs, or a mix of the 2017 and 2019 API versions.

DynamoDB LSI Item Collection 10 GB Limit — Causes & Fix

Tables with a Local Secondary Index cap each item collection at 10 GB — cross it and writes fail. Monitor ItemCollectionMetrics and re-shard.

DynamoDB Cannot Access Stream — Stream Not Enabled Fix

A consumer read a DynamoDB stream on a table with Streams turned off, or used a stale ARN. Enable Streams and point it at the current LatestStreamArn.

DynamoDB TableAlreadyExistsException / "Table already exists" — Fix

Restores throw TableAlreadyExistsException; CreateTable and ImportTable report ResourceInUseException. The target name is taken, so pick a new one.

DynamoDB Streams ExpiredIteratorException — Causes & Fix

A DynamoDB Streams shard iterator is valid for 15 minutes. Use it later and GetRecords throws ExpiredIteratorException. How to resume without data loss.

DynamoDB Streams TrimmedDataAccessException — Causes & Fix

Stream records live 24 hours, so a checkpoint older than that throws TrimmedDataAccessException. Resume from TRIM_HORIZON and reconcile from the table.

DynamoDB BackupInUseException — Causes & Fix

DynamoDB BackupInUseException means another backup operation on the same table is still running. Wait for it to finish, then retry your call.

DynamoDB InvalidRestoreTimeException — Causes & Fix

InvalidRestoreTimeException means your RestoreDateTime falls outside the table's PITR window of up to 35 days. Pick a RestoreDateTime inside the table's PITR window (up to 35 days).

DynamoDB PointInTimeRecoveryUnavailableException — Fix

You tried a point-in-time restore on a table that never had PITR enabled. Enable continuous backups now, and use an on-demand backup for today's data.

DynamoDB GlobalTableNotFoundException — Causes & Fix

GlobalTableNotFoundException means the legacy global-table APIs can't see your table — usually a 2019.11.21 global table managed through UpdateTable.

DynamoDB ReplicaAlreadyExistsException — Causes & Fix

You asked DynamoDB to add a replica Region already in the global table. Describe the replication group first, and make replica management idempotent.

Auth & configuration errors (13)

"not authorized to perform dynamodb:..." — AccessDeniedException Fix

DynamoDB AccessDeniedException means your IAM identity is not authorized for the action named in the message. How to read it and fix the IAM policy.

"ConfigError: Missing region in config" — DynamoDB Fix

The AWS SDK couldn't work out which region to send DynamoDB requests to. Set it on the client, via AWS_REGION, or in your AWS config — here's each option.

"The security token included in the request is invalid" — DynamoDB Fix

This UnrecognizedClientException means your AWS credentials are wrong, expired, or not being picked up. Check access keys, session token expiry, and which profile the SDK loaded.

DynamoDB IncompleteSignatureException — Causes & Fix

IncompleteSignatureException means the SigV4 signature was malformed — usually hand-rolled signing, or a proxy that rewrote the Authorization header.

"The security token included in the request is expired" — DynamoDB Fix

ExpiredTokenException means your temporary STS, SSO or assumed-role credentials timed out. Re-run aws sso login and clear any stale AWS_SESSION_TOKEN.

"Unable to locate credentials" (boto3 / DynamoDB) — Fix

boto3 raises NoCredentialsError when nothing in its provider chain supplies AWS credentials — no env vars, no profile, no instance role.

"The request signature we calculated does not match" — Fix

DynamoDB returns InvalidSignatureException, not SignatureDoesNotMatch, when SigV4 signing fails. Usually a wrong secret key or clock skew on your machine.

"Credential should be scoped to a valid region" — DynamoDB Fix

This SigV4 error means the region in your credential scope does not match the region you actually called. How to line up client and endpoint regions.

"InvalidSignatureException: Signature expired" — DynamoDB Fix

DynamoDB rejects a request whose signed timestamp is more than five minutes off AWS server time. Almost always client clock skew. Sync the client clock and resign.

"Missing Authentication Token" — DynamoDB Error Fix

A MissingAuthenticationTokenException from DynamoDB means a wrong endpoint URL or path, or a request that never got signed. Check the endpoint URL, path, and that the request is SigV4-signed.

"Could not load credentials from any providers" (DynamoDB) — Fix

The AWS SDK for JavaScript v3 raises CredentialsProviderError when its whole credential chain comes up empty. How the chain resolves, and each fix.

"The SSO session associated with this profile has expired" — Fix

An expired IAM Identity Center token breaks AWS CLI and SDK calls to DynamoDB. Run aws sso login, and clear a stale ~/.aws/sso/cache if that isn't enough.

"The config profile could not be found" — AWS CLI & boto3 Fix

The AWS CLI and boto3 raise ProfileNotFound when the named profile is missing from ~/.aws/config. The three usual causes and the fix for each.

DynamoDB Local & setup errors (8)

"Unable to start DynamoDB Local process" — Fix

DynamoDB Local failed to launch — usually a missing/incompatible Java runtime, a port already in use, or a bad install path. Check the Java runtime, port conflicts, and install path.

"Could not connect to DynamoDB Local" (ECONNREFUSED) — Fix

ECONNREFUSED against DynamoDB Local means nothing is listening. Usually the emulator is not running, the port is wrong, or the SDK is hitting real AWS.

"Could not connect to the endpoint URL" (DynamoDB) — Fix

botocore raises EndpointConnectionError when it cannot reach DynamoDB. Usually a wrong endpoint URL, DynamoDB Local not running, or a bad region.

DynamoDB Local "Address already in use" (port 8000) — Fix

DynamoDB Local throws java.net.BindException when something already owns port 8000. How to find the process, free the port, or start Local on another port.

DynamoDB Local "Failed to load native library sqlite4java" — Fix

DynamoDB Local dies at startup with an UnsatisfiedLinkError for sqlite4java, caused by a wrong java.library.path or an Apple Silicon arch mismatch.

"Unable to execute HTTP request" (DynamoDB, Java SDK) — Fix

The AWS SDK for Java fails with Unable to execute HTTP request when it cannot reach the endpoint. DynamoDB Local down, wrong port, or Docker networking.

"Cannot do operations on a non-existent table" (DynamoDB Local) — Fix

DynamoDB Local gives each credentials and region pair its own database, so a table you created can be invisible. Run Local with -sharedDb to share one.

DynamoDB Local UnsupportedClassVersionError — Fix

DynamoDB Local 2.6.0 and newer needs Java 17 or later. On an older JRE the JVM refuses to load it. Install a current JDK or run the Docker image.

How these are verified

Documentation paraphrases its own implementation, and the paraphrase drifts. Every error message quoted on these pages was produced by running the failing call against the real AWS DynamoDB service and recording what came back, character for character — not copied out of the AWS docs.

Not DynamoDB Local. The emulator is convenient, but AWS makes no promise that it words errors the way the service does — and when we checked, more than half of its messages differed. Where the difference is worth knowing, the page shows both.

The only edits are to the parts that describe your request rather than the error: the table name, and the copy of your payload the service echoes back. A test fails the build if any page quotes a string the service never returned — it exists because one of our own pages quoted an invented message for months before anyone ran the code.

58 messages across 14 exception types: 55 captured against the live service, 2 rejected by the SDK before a request was sent, and 1 where DynamoDB Local’s own wording is the subject. 6 carry a note on how the emulator words the same failure.

Live service: Amazon DynamoDB (live service, us-east-1)
Emulator (for comparison): DynamoDB Local (amazon/dynamodb-local)
JavaScript SDK: @aws-sdk/client-dynamodb 3.1096.0
Python SDK: boto3 1.43.81 on Python 3.14.7
Node.js: v24.20.0

More DynamoDB resources

A structured DynamoDB curriculum, from the fundamentals through to the internals.

DynamoDB Code Examples

Copy-paste snippets for every operation — SDK v3, boto3, and the AWS CLI.

Straight answers to the DynamoDB questions developers ask most.

Engineering Blog

How DynoTable is built — the stories behind the AI agent and the MCP server.

Expression builder, pricing and capacity calculators — right in your browser.

Work with DynamoDB without the Console

A fast DynamoDB desktop client that runs the real SQL DynamoDB can’t — JOINs, GROUP BY, aggregates — with visual editing and an AI agent on your own Bedrock keys.

Free 30-day trial, no credit card — then the Free plan with no time limit.