DynamoDB Streams: ExpiredIteratorException

TL;DR — Shard iterator dari GetShardIterator hanya valid selama 15 menit. Jika konsumen Anda berhenti sejenak, memproses batch dengan lambat, atau menahan iterator lintas restart, panggilan GetRecords berikutnya melempar ini. Pulihkan dengan meminta iterator baru — gunakan AFTER_SEQUENCE_NUMBER dengan sequence number terakhir yang Anda proses agar Anda melanjutkan persis di tempat Anda berhenti.

Apa artinya

ExpiredIteratorException: The provided iterator exceeds the maximum age allowed.

Membaca stream DynamoDB secara langsung adalah loop dua langkah: GetShardIterator memberi Anda handle posisi ke dalam shard, dan setiap panggilan GetRecords mengonsumsinya dan mengembalikan yang berikutnya (NextShardIterator). Setiap handle itu kedaluwarsa 15 menit setelah dikeluarkan. Exception tidak berarti data hilang — rekaman stream hidup selama 24 jam — ia hanya berarti handle posisi ini usang dan Anda butuh yang baru.

Mengapa terjadi

Pemrosesan lambat antar poll — pekerjaan per batch (tulis, panggilan eksternal) memakan waktu lebih dari 15 menit sebelum GetRecords berikutnya.
Konsumen yang berhenti atau ditangguhkan — worker yang dihentikan, deploy panjang, atau sesi debugger yang menahan loop.
Menyimpan iterator — mempertahankan string iterator (di DB atau checkpoint) dan menggunakannya kembali nanti; iterator bersifat ephemeral, sequence number tidak.
Backoff yang berlangsung lama — loop error-retry yang tidur melampaui jendela.

Cara memperbaikinya

Tangkap dan seed ulang iterator dari checkpoint terakhir Anda — lacak SequenceNumber dari rekaman terakhir yang Anda proses, lalu:
```
const {ShardIterator} = await streams.send(
  new GetShardIteratorCommand({
    StreamArn: streamArn,
    ShardId: shardId,
    ShardIteratorType: 'AFTER_SEQUENCE_NUMBER',
    SequenceNumber: lastProcessedSequenceNumber
  })
);
```
Belum ada checkpoint? TRIM_HORIZON memproses ulang shard dari rekaman tertua yang tersedia; LATEST melompat ke aktivitas baru.
Checkpoint sequence number, jangan pernah iterator — sequence number adalah titik lanjut yang tahan lama.
Jaga loop poll tetap ketat — lakukan pekerjaan per-rekaman yang berat secara asinkron (antrekan) agar irama GetRecords tetap jauh di dalam 15 menit.
Utamakan konsumen terkelola — Lambda event source mapping dan DynamoDB Streams Kinesis Adapter (KCL) mengelola iterator dan checkpoint untuk Anda; loop GetRecords buatan sendiri adalah tempat exception ini hidup.

Pastikan penanganan Anda idempoten: melanjutkan dari checkpoint dapat mengirim ulang rekaman yang Anda proses setengah. Stream itu sendiri berisi setiap rekaman tepat satu kali, tetapi konsumen yang seed ulang dari checkpoint terakhirnya secara efektif memproses at-least-once.

Men-debug apa yang sebenarnya dipancarkan stream jauh lebih mudah ketika Anda dapat melihat item berubah — aplikasi desktop DynoTable menunjukkan keadaan live item sehingga Anda dapat mencocokkan rekaman stream dengan data. Memperkirakan biaya baca dari replay catch-up? Kalkulator harga DynamoDB siap membantu.

Kesalahan terkait

TrimmedDataAccessException — Anda tertinggal di belakang jendela retensi 24 jam (data benar-benar hilang).
Stream not enabled
Invalid StreamArn
Pelajari: DynamoDB Streams

References

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.