DynamoDB TransactionCanceledException — ConditionalCheckFailed

TL;DR — TransactWriteItems がキャンセルされ、CancellationReasons 配列に ConditionalCheckFailed エントリが含まれています。トランザクションの条件式のいずれかが成立しなかったため、DynamoDB は すべての アクションをアトミックにロールバックしました。理由配列を読みましょう。そのエントリは位置対応で、リクエストされたアイテムごとに1つあります。どのアイテムの条件が失敗したかを見つけ、そのアイテムの前提条件またはデータを修正してください。

意味

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

TransactWriteItems はオールオアナッシングです。いずれか1つのアクションの ConditionExpression が false と評価されると、DynamoDB はリクエスト全体をキャンセルし、アイテムごとの理由リストを報告します。位置 i の ConditionalCheckFailed は、i 番目のアイテムの条件が満たされなかったことを意味します。トランザクションは部分的にも適用されませんでした。

発生する理由

• オプティミスティックロックの失敗 — version = :v / attribute_not_exists(pk) のガードが失敗した。別のライターがすでにアイテムを変更または作成していたため。
• 一意性ガードの発動 — attribute_not_exists(pk) の挿入が競合に負け、アイテムがすでに存在している。
• 古い読み取り — 条件が、その後変更された値から組み立てられていた。
• 理由リストの誤読 — 配列は 位置対応 で、TransactItems と同じ順序です。あるスロットの None はそのアイテムが問題なかったことを意味し、ConditionalCheckFailed が失敗したものを示します。（配列内の他のコード — TransactionConflict、ItemCollectionSizeLimitExceeded、ProvisionedThroughputExceeded、ThrottlingError、ValidationError — は別のことを意味します。）

修正方法

1. 例外内の CancellationReasons を調べ、ConditionalCheckFailed を持つインデックスを見つけます。それが失敗したアクションです。
2. アイテムを再読み取り して判断します: 新鮮な前提条件で再試行する（オプティミスティックロックのリトライループ）か、呼び出し元に競合を報告するか。
3. 条件が誤っていれば 修正します — 例: 正当にすでに存在するアイテムに対する attribute_not_exists(pk)。
4. 失敗したアクションに ReturnValuesOnConditionCheckFailure: ALL_OLD を追加 すると、DynamoDB が条件を破ったアイテムを返します（デバッグに最適）。
5. リトライに上限を設けます — 恒常的に失敗する条件は、一時的なエラーではなく実際のビジネス上の競合です。永遠に再試行しないでください。

失敗したトランザクションを手作業でデバッグしていますか？再試行する前に、DynoTable デスクトップアプリ で現在のアイテムの状態を調べ、なぜ前提条件が成立しなかったのかを正確に確認しましょう。

FAQ

トランザクションのどのアイテムが失敗したかをどうやって知るのですか？ TransactionCanceledException の CancellationReasons 配列を読みます。位置対応で、リクエストされたアイテムごとに1エントリが順序どおりに並びます。コード ConditionalCheckFailed のエントリが、条件式が false と評価されたアクションを特定します。コード None のエントリは成功したものです。

トランザクション内の ConditionalCheckFailed はリトライ可能ですか？ 自動的にはできません。これは一時的なエラーではなく、実際の前提条件の競合です。アイテムを再読み取りし、書き込みがまだ適用されるかを判断し、新鮮な条件で再試行するか、ユーザーに競合を提示してください。

関連するエラー

• ConditionalCheckFailedException — 単一の非トランザクション書き込みでの同じ失敗。
• TransactionCanceledException (overview) — すべてのキャンセル理由コード。
• TransactionConflictException — 同じアイテムに対する並行トランザクション。
• Code example: TransactWriteItems in Node.js · in Python (boto3) — 適応可能な、条件付きの動作するトランザクション。
• Learn: DynamoDB transactions · Condition expressions

References

• TransactWriteItems — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide
• DynamoDB condition expression examples — Amazon DynamoDB Developer Guide

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。