DynamoDB Streams: TrimmedDataAccessException

TL;DR — DynamoDB Streams 保留記錄 24 小時；更舊的記錄被修剪並從 stream 消失。這個例外表示你要求了一個已被修剪的位置 — 一個超過一天的 checkpoint,通常來自一個停機或落後的消費者。你無法從 stream 取回那些記錄:從 TRIM_HORIZON（最舊的倖存記錄）繼續,並從表格本身調解缺口。

這是什麼意思

TrimmedDataAccessException: The data you are trying to access has been trimmed.

與過期的 iterator（只有你的_位置控制代碼_過時）不同,被修剪的資料是真正被移除的。在被修剪的 SequenceNumber 要求 shard iterator,或讀取記錄已老化淘汰的 shard,會拋出這個。stream 是一個滾動的 24 小時緩衝,而非封存。

為什麼會發生

• 消費者停機超過 24 小時 — 故障、暫停的 worker、被遺忘的停用觸發器 — 而其 checkpoint 現在指向已修剪的範圍。
• 處理延遲超過保留期 — 消費者執行中,但慢於寫入速率,並漂移超過一天。
• 過時的已儲存 checkpoint — 以數週前持久化的 SequenceNumber 重新啟動舊的消費者。
• 端到端讀取舊 shard — 走遍長壽 stream 的 shard 血統並要求早於保留期的範圍。

如何修正

1. 從最舊的可用記錄繼續並接受缺口:

   const {ShardIterator} = await streams.send(
     new GetShardIteratorCommand({
       StreamArn: streamArn,
       ShardId: shardId,
       ShardIteratorType: 'TRIM_HORIZON' // oldest untrimmed record
     })
   );

   若只有新活動重要,改用 LATEST。

2. 從真相來源調解錯過的視窗 — 表格仍有每個項目的_當前_狀態。對受影響的鍵做有界的 Scan/Query（或對大型表格做匯出）可重建被修剪記錄本會告訴你的內容,減去中間版本。

3. 對消費者延遲發出警示 — 監控你正在處理的記錄年齡（或 Lambda 的 IteratorAge 指標）並在它接近 24 小時前很久就通知。

4. 需要更長的保留期? 在記錄抵達時將它們串流到持久緩衝（例如透過 Kinesis adapter 模式的 Kinesis Data Streams,或自行持久化已處理的記錄）— DynamoDB Streams 本身無法延長超過 24 小時。

在缺口後重建狀態意味著看現在表格中實際有什麼 — DynoTable 桌面應用程式讓那次調解變成可瀏覽的查詢而非指令碼。估算追趕讀取?DynamoDB 定價計算器估算 RCU 成本。

相關錯誤

• ExpiredIteratorException — 可復原的表親:位置過時,資料仍在。
• Stream not enabled
• Invalid StreamArn
• 學習：DynamoDB Streams

References

• GetRecords — Amazon DynamoDB Streams API Reference
• GetShardIterator — Amazon DynamoDB Streams API Reference
• Change data capture for DynamoDB Streams — Amazon DynamoDB Developer Guide

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。