DynamoDB TransactionCanceledException — ConditionalCheckFailed

TL;DR — TransactWriteItems Anda dibatalkan dan array CancellationReasons berisi entri ConditionalCheckFailed. Salah satu condition expression transaksi tidak terpenuhi, jadi DynamoDB menggulung balik setiap aksi secara atomik. Baca array reasons — entrinya bersifat posisional, satu per item yang diminta — untuk menemukan kondisi item mana yang gagal, lalu perbaiki prasyarat item itu atau datanya.

Apa artinya

TransactionCanceledException: Transaction cancelled, please refer cancellation
reasons for specific reasons [ConditionalCheckFailed, None, None]
# CancellationReasons[0] = { Code: "ConditionalCheckFailed",
#                            Message: "The conditional request failed" }

# what the engine actually returns, reproduced against DynamoDB Local:
TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed]

TransactWriteItems bersifat semua-atau-tidak-sama-sekali. Jika ConditionExpression dari salah satu aksi bernilai false, DynamoDB membatalkan seluruh permintaan dan melaporkan daftar alasan per item. ConditionalCheckFailed di posisi i berarti kondisi item ke-i tidak terpenuhi — transaksi tidak pernah diterapkan sebagian.

Mengapa itu terjadi

Optimistic-lock meleset — penjaga version = :v / attribute_not_exists(pk) gagal karena penulis lain sudah mengubah atau membuat item.
Penjaga keunikan terpicu — sisipan attribute_not_exists(pk) kalah dalam balapan, jadi item sudah ada.
Baca usang — kondisi dibangun dari nilai yang sejak itu telah berubah.
Daftar alasan salah dibaca — array bersifat posisional, diurutkan seperti TransactItems Anda; None pada suatu slot berarti item itu baik-baik saja, ConditionalCheckFailed menandai yang gagal. (Kode lain dalam array — TransactionConflict, ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, ThrottlingError, ValidationError — berarti hal yang berbeda.)

Bagaimana cara memperbaikinya

Periksa CancellationReasons dalam exception dan temukan indeks dengan ConditionalCheckFailed — itulah aksi yang gagal.
Baca ulang item dan putuskan: coba lagi dengan prasyarat baru (loop retry optimistic-lock) atau munculkan konflik ke pemanggil.
Perbaiki kondisi jika salah — mis. attribute_not_exists(pk) pada item yang secara sah sudah ada.
Tambahkan ReturnValuesOnConditionCheckFailure: ALL_OLD ke aksi yang gagal agar DynamoDB mengembalikan item yang melanggar kondisi (bagus untuk debugging).
Batasi retry Anda — kondisi yang gagal terus-menerus adalah konflik bisnis nyata, bukan kesalahan transien; jangan coba lagi selamanya.

Men-debug transaksi gagal secara manual? Staging area DynoTable menampilkan keadaan item saat ini di samping perubahan tertunda Anda, sehingga Anda dapat melihat persis mengapa prasyarat tidak terpenuhi sebelum Anda coba lagi.

FAQ

Bagaimana saya tahu item mana dalam transaksi saya yang gagal? Baca array CancellationReasons pada TransactionCanceledException. Ia bersifat posisional — satu entri per item yang diminta, berurutan. Entri dengan kode ConditionalCheckFailed mengidentifikasi aksi yang condition expression-nya bernilai false; entri dengan kode None berhasil.

Apakah ConditionalCheckFailed di dalam transaksi dapat dicoba ulang? Tidak secara otomatis. Ini konflik prasyarat nyata, bukan kesalahan transien. Baca ulang item, putuskan apakah tulisan masih berlaku, dan coba lagi dengan kondisi baru — atau munculkan konflik ke pengguna.

Kesalahan terkait

ConditionalCheckFailedException — kegagalan yang sama pada satu tulisan non-transaksional.
TransactionCanceledException (overview) — semua kode alasan pembatalan.
TransactionConflictException — transaksi bersamaan pada item yang sama.
Contoh kode: TransactWriteItems in Node.js · in Python (boto3) — transaksi berkondisi yang berfungsi untuk diadaptasi.
Pelajari: DynamoDB transactions · Condition expressions

Referensi

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