Diagnosing and Fixing DynamoDB TTL Expiration Failures

Recognizing the Problem

When you notice that items you expect to be removed by Time‑to‑Live (TTL) are still present, the first symptom is a lack of activity in the ExpiredItemDeleteTime CloudWatch metric and a persistent count of items in the table. TTL is an asynchronous background process; if it isn’t firing, items will never be deleted.

Common Causes

Cause	Typical Indicator
TTL attribute missing or mis‑named	Query shows no attribute with the configured name.
TTL attribute wrong data type	Attribute is a string or binary instead of a numeric epoch timestamp.
TTL not enabled on the table	Describe‑TTL returns TimeToLiveStatus: DISABLED.
TTL values in the past or far future	Items expire immediately or never expire.
TTL engine stalled or throttled	CloudWatch shows zero expired items despite many eligible items.

Diagnostic Checklist

1. Verify TTL configuration
   • Run on a machine with AWS CLI v2 and IAM permissions for dynamodb:DescribeTimeToLive. aws dynamodb describe-time-to-live --table-name
   • Check TimeToLiveStatus (should be ENABLED) and AttributeName (matches your TTL column).
2. Inspect a sample item
   • Retrieve an item that should have expired. aws dynamodb get-item --table-name --key '{"PK": {"S": "SampleKey"}}'
   • Confirm the TTL attribute exists, is a number, and represents epoch seconds (e.g., 1697107200).
3. Check CloudWatch metrics
   • Navigate to the DynamoDB dashboard in the CloudWatch console.
   • Verify that ExpiredItemDeleteTime shows non‑zero values and that ConsumedWriteCapacityUnits is within expected ranges.
4. Validate time zone and epoch conversion
   • Ensure the timestamp is UTC epoch seconds, not milliseconds or local time.
   • Use date +%s on Linux/macOS or Get-Date -UFormat %s on PowerShell to generate a correct value.

Fixes Tied to Findings

Finding	Action
TTL attribute missing or mis‑named	Update the table schema to include the correct attribute name and set it on all existing items. Use a batch write script or UpdateItem calls.
TTL attribute wrong data type	Convert the attribute to a number. If it’s a string, use UpdateItem with AttributeValueList to cast or re‑insert the item.
TTL not enabled	Enable TTL: aws dynamodb update-time-to-live --table-name --time-to-live-specification Enabled=true,AttributeName=
TTL values in past/future	Recalculate the epoch value to a realistic future timestamp (e.g., now + 30 days) and update the items.
TTL engine stalled	Check account limits: ConsumedWriteCapacityUnits should not be near the provisioned limit. Consider increasing write capacity or switching to on‑demand. Verify that no other processes are throttling the table.

Example: Enabling TTL on a Table

# Enable TTL on  using the attribute "ttl"
aws dynamodb update-time-to-live \
  --table-name MyTable \
  --time-to-live-specification Enabled=true,AttributeName=ttl

After running this command, wait a few minutes for the TTL engine to pick up the new setting. Verify with describe-time-to-live and check CloudWatch metrics again.

Example: Correcting a Wrong Data Type

# Convert "ttl" from string to number for a specific item
aws dynamodb update-item \
  --table-name MyTable \
  --key '{"PK": {"S": "Item123"}}' \
  --update-expression "SET ttl = :newVal" \
  --expression-attribute-values '{":newVal": {"N": "1697107200"}}'

Verification After Fixes

1. Wait 10–15 minutes for the TTL engine to process.
2. Query the item again. It should no longer appear in the table.
3. Confirm CloudWatch shows increased ExpiredItemDeleteTime and that ConsumedWriteCapacityUnits for the table remains stable.

Limitations & Practical Checks

• TTL deletions are asynchronous; items may persist up to a few minutes after expiry.
• Large tables can experience delayed deletions due to background job scheduling.
• Always test changes on a staging environment before production.
• Use aws dynamodb scan with a filter on the TTL attribute to quickly spot problematic items.

Escalation Criteria

If after completing all checks and fixes you still see no TTL activity, consider:

• Contacting AWS Support with the table name, region, and a snapshot of the TTL configuration.
• Reviewing account‑level write capacity limits or DynamoDB on‑demand usage patterns.
• Checking for any CloudWatch alarms or Lambda functions that might interfere with TTL processing.

Diagram Labels

TTL Attribute

TTL Engine

CloudWatch Metrics

Table Items