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" }

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? Inspiziere den aktuellen Item-Zustand in der DynoTable-Desktop-App, um genau zu sehen, warum die Vorbedingung nicht hielt, bevor du 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 example: TransactWriteItems in Node.js · in Python (boto3) — eine funktionierende bedingte Transaktion zum Anpassen.
• 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

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