DynamoDB TransactionCanceledException — ConditionalCheckFailed

TL;DR — Dein TransactWriteItems wurde abgebrochen und das CancellationReasons-Array enthält einen ConditionalCheckFailed-Eintrag. Eine der Condition-Expressions der Transaktion hielt nicht, also hat DynamoDB jede Aktion atomar zurückgerollt. Lies das Reasons-Array — seine Einträge sind positionsbezogen, einer pro angefordertem Item — um herauszufinden, welches Item die Bedingung nicht erfüllte, und behebe dann die Vorbedingung dieses Items oder die Daten.

Was es bedeutet

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 ist alles-oder-nichts. Wenn das ConditionExpression einer einzelnen Aktion zu false ausgewertet wird, bricht DynamoDB die ganze Anfrage ab und meldet eine Liste von Gründen pro Item. ConditionalCheckFailed an Position i bedeutet, dass die Bedingung des i-ten Items nicht erfüllt war — die Transaktion wurde nie teilweise angewendet.

Warum es passiert

• Optimistic-Lock-Miss — ein version = :v / attribute_not_exists(pk) Guard schlug fehl, weil ein anderer Writer das Item bereits geändert oder erstellt hat.
• Uniqueness-Guard ausgelöst — ein attribute_not_exists(pk)-Insert verlor ein Wettrennen, das Item existiert also bereits.
• Veralteter Read — die Bedingung wurde aus einem Wert gebaut, der sich seither geändert hat.
• Reasons-Liste falsch gelesen — das Array ist positionsbezogen, geordnet wie deine TransactItems; ein None an einer Stelle bedeutet, dass dieses Item in Ordnung war, ConditionalCheckFailed markiert das fehlgeschlagene. (Andere Codes im Array — TransactionConflict, ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, ThrottlingError, ValidationError — bedeuten etwas anderes.)

So behebst du es

1. Untersuche CancellationReasons in der Exception und finde den Index mit ConditionalCheckFailed — das ist die fehlgeschlagene Aktion.
2. Lies das Item neu und entscheide: erneut mit einer frischen Vorbedingung versuchen (Optimistic-Lock-Retry-Schleife) oder dem Aufrufer einen Konflikt melden.
3. Behebe die Bedingung, falls sie falsch ist — z. B. attribute_not_exists(pk) auf einem Item, das legitimerweise bereits existiert.
4. Füge ReturnValuesOnConditionCheckFailure: ALL_OLD zur fehlgeschlagenen Aktion hinzu, sodass DynamoDB das Item zurückgibt, das die Bedingung brach (großartig zum Debuggen).
5. Begrenze deine Retries — eine dauerhaft fehlschlagende Bedingung ist ein echter Business-Konflikt, kein vorübergehender Fehler; wiederhole nicht ewig.

Eine fehlgeschlagene Transaktion von Hand debuggen? DynoTables Staging-Bereich zeigt den aktuellen Item-Zustand neben deiner ausstehenden Änderung, sodass du genau siehst, warum die Vorbedingung nicht hielt, bevor du es erneut versuchst.

FAQ

Woher weiß ich, welches Item in meiner Transaktion fehlschlug? Lies das CancellationReasons-Array auf der TransactionCanceledException. Es ist positionsbezogen — ein Eintrag pro angefordertem Item, in Reihenfolge. Der Eintrag mit Code ConditionalCheckFailed identifiziert die Aktion, deren Condition-Expression zu false ausgewertet wurde; Einträge mit Code None waren erfolgreich.

Ist ein ConditionalCheckFailed innerhalb einer Transaktion wiederholbar? Nicht automatisch. Es ist ein echter Vorbedingungs-Konflikt, kein vorübergehender Fehler. Lies das Item neu, entscheide, ob der Write noch gilt, und wiederhole mit einer frischen Bedingung — oder melde dem Nutzer den Konflikt.

Verwandte Fehler

• ConditionalCheckFailedException — derselbe Fehler bei einem einzelnen nicht-transaktionalen Write.
• TransactionCanceledException (overview) — alle Abbruchgrund-Codes.
• TransactionConflictException — eine gleichzeitige Transaktion auf demselben Item.
• Code-Beispiel: TransactWriteItems in Node.js · in Python (boto3) — eine funktionierende bedingte Transaktion zum Anpassen.
• Lernen: DynamoDB-Transaktionen · Condition-Expressions

Referenzen

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

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.