How to fix TrimmedDataAccessException: The requested data has been trimmed in DynamoDB

DynamoDBINTERMEDIATEMEDIUMUpdated Dec 22, 2025· 96 views

TrimmedDataAccessException happens when a DynamoDB Streams consumer tries to read a record that was already evicted by the 24‑hour retention window. The SDK throws this exception with HTTP 400, and GetRecords will not return data until you recreate the iterator inside the retention window.

Quick fix

Fixes TrimmedDataAccessException: The requested data has been trimmed

  1. Confirm retention period and iterator age
  2. Recreate the iterator inside the retention window
  3. Handle trimmed exceptions gracefully
dynamodb — error
# TrimmedDataAccessException: The requested data has been trimmed
TrimmedDataAccessException: The requested data has been trimmed

What this error means

The TrimmedDataAccessException error means that your stream consumer is asking for a record that no longer exists because DynamoDB trims records older than 24 hours. The operation ran past the oldest record in a shard, either because the shard iterator references a sequence number older than the trim point or because a record aged out between the time you created the iterator and the moment you called GetRecords. The SDK surfaces the human-readable message “The data you are trying to access has been trimmed.” to highlight that continuous consumption fell behind the retention window.

Typical symptoms

  • HTTP 400 responses with TrimmedDataAccessException and “The requested data has been trimmed”
  • KCL/Kinesis Client logs repeating the exception every cycle after the consumer wakes from an outage
  • GetRecords loops never return records even though the stream still contains newer items
  • Application alerts show stale shard iterators or checkpoints that keep fetching trimmed data

Common causes

  1. Checkpoint or shard iterator points to a sequence number older than DynamoDB Streams’ retention window (default 24 hours)
  2. Consumer was offline longer than the retention period and resumed with the old iterator
  3. GetRecords call takes so long that the referenced record is trimmed before the request arrives
  4. Retention period has been shortened or set to the default while the consumer still references historic data
  5. Stale KCL checkpoint table entry that keeps giving TrimmedDataAccessException on restart

How to fix "TrimmedDataAccessException: The requested data has been trimmed"

1Confirm retention period and iterator age

Describe the stream and inspect RetentionPeriodHours plus the shard iterator you are using:

https://docs.aws.amazon.com/cli/latest/reference/dynamodbstreams/describe-stream.html#examples

1. Run aws dynamodbstreams describe-stream --stream-arn <arn> to read RetentionPeriodHours. The default is 24 hours.
2. Compare the iterator type you request (AT_SEQUENCE_NUMBER, AT_TIMESTAMP, TRIM_HORIZON, LATEST) with the sequence number stored in the checkpoint.
3. If you are using AT_SEQUENCE_NUMBER or a saved checkpoint, verify the sequence number is within the last 24 hours; anything older has been trimmed and cannot be read.

2Recreate the iterator inside the retention window

When the iterator has been trimmed, lesion handler must skip ahead to a fresh position:

1. Use TRIM_HORIZON (to replay everything still in retention) or LATEST (to start from the newest data) instead of the stale shard iterator.
2. Alternatively, call GetShardIterator with AT_TIMESTAMP and a timestamp that is now minus the retention window to jump just before the oldest available record.
3. For Kinesis Client Library consumers, clear the checkpoint for the affected shard (the ~cl table) so it reinitializes using a new iterator and not an expired sequence number.

This ensures the next GetRecords request points to a record that still exists inside DynamoDB Streams’ trim horizon.

3Handle trimmed exceptions gracefully

Catch TrimmedDataAccessException and treat it as a signal to reset your checkpoint instead of retrying the same iterator:

npm install @aws-sdk/client-dynamodb-streams

switch (error.name) {
 case 'TrimmedDataAccessException':
 // log the event, optionally notify, then reset the shard iterator
 await resetCheckpointShard(/* shardId */);
 continue; // or break and restart consumer loop
 default:
 throw error;
 }

Add alerts on repeated TrimmedDataAccessException spikes and monitor GetRecords error metrics. If consumers regularly fall behind hopes beyond 24 hours, consider increasing the stream retention window (up to 7 days) or keeping the application online longer.

Frequently asked questions

What does "TrimmedDataAccessException: The requested data has been trimmed" mean?
The TrimmedDataAccessException error means that your stream consumer is asking for a record that no longer exists because DynamoDB trims records older than 24 hours. The operation ran past the oldest record in a shard, either because the shard iterator references a sequence number older than the trim point or because a record aged out between the time you created the iterator and the moment you called GetRecords. ” to highlight that continuous consumption fell behind the retention window.
How do I fix "TrimmedDataAccessException: The requested data has been trimmed"?
TrimmedDataAccessException happens when a DynamoDB Streams consumer tries to read a record that was already evicted by the 24‑hour retention window. The SDK throws this exception with HTTP 400, and GetRecords will not return data until you recreate the iterator inside the retention window.
What causes "TrimmedDataAccessException: The requested data has been trimmed"?
Checkpoint or shard iterator points to a sequence number older than DynamoDB Streams’ retention window (default 24 hours) Consumer was offline longer than the retention period and resumed with the old iterator GetRecords call takes so long that the referenced record is trimmed before the request arrives
Is the "TrimmedDataAccessException: The requested data has been trimmed" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading