DynamoDB TransactionCanceledException — ConditionalCheckFailed

In breve — Il tuo TransactWriteItems è stato annullato e l'array CancellationReasons contiene una voce ConditionalCheckFailed. Una delle espressioni di condizione della transazione non era soddisfatta, quindi DynamoDB ha fatto il rollback di ogni azione in modo atomico. Leggi l'array delle ragioni — le sue voci sono posizionali, una per Item richiesto — per trovare quale condizione di quale Item è fallita, poi correggi la precondizione di quell'Item o i dati.

Cosa significa

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 è tutto-o-niente. Se il ConditionExpression di una singola azione risulta falso, DynamoDB annulla l'intera richiesta e riporta un elenco di ragioni per Item. ConditionalCheckFailed alla posizione i significa che la condizione dell'i-esimo Item non è stata soddisfatta — la transazione non è mai stata applicata parzialmente.

Perché succede

Miss del lock ottimistico — un guard version = :v / attribute_not_exists(pk) è fallito perché un altro writer ha già modificato o creato l'Item.
Guard di unicità attivato — un inserimento attribute_not_exists(pk) ha perso una race, quindi l'Item esiste già.
Lettura obsoleta — la condizione è stata costruita da un valore che nel frattempo è cambiato.
Elenco delle ragioni letto male — l'array è posizionale, ordinato come i tuoi TransactItems; un None in una posizione significa che quell'Item era a posto, ConditionalCheckFailed segna quello fallito. (Altri codici nell'array — TransactionConflict, ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, ThrottlingError, ValidationError — significano qualcosa di diverso.)

Come risolverlo

Ispeziona CancellationReasons nell'eccezione e trova l'indice con ConditionalCheckFailed — quella è l'azione fallita.
Rileggi l'Item e decidi: riprova con una precondizione aggiornata (loop di retry con lock ottimistico) o segnala un conflitto al chiamante.
Correggi la condizione se è sbagliata — es. attribute_not_exists(pk) su un Item che legittimamente esiste già.
Aggiungi ReturnValuesOnConditionCheckFailure: ALL_OLD all'azione fallita così DynamoDB restituisce l'Item che ha violato la condizione (ottimo per il debug).
Limita i tuoi retry — una condizione che fallisce persistentemente è un vero conflitto di business, non un errore transitorio; non riprovare all'infinito.

Stai facendo il debug di una transazione fallita a mano? L'area di staging di DynoTable mostra lo stato attuale dell'Item accanto alla tua modifica in sospeso, così puoi vedere esattamente perché la precondizione non era soddisfatta prima di riprovare.

FAQ

Come faccio a sapere quale Item della mia transazione è fallito? Leggi l'array CancellationReasons sulla TransactionCanceledException. È posizionale — una voce per Item richiesto, in ordine. La voce con codice ConditionalCheckFailed identifica l'azione la cui espressione di condizione è risultata falsa; le voci con codice None sono riuscite.

Un ConditionalCheckFailed all'interno di una transazione è ripetibile? Non automaticamente. È un vero conflitto di precondizione, non un errore transitorio. Rileggi l'Item, decidi se la scrittura si applica ancora, e riprova con una condizione aggiornata — oppure segnala il conflitto all'utente.

Errori correlati

ConditionalCheckFailedException — lo stesso fallimento su una singola scrittura non transazionale.
TransactionCanceledException (overview) — tutti i codici delle ragioni di annullamento.
TransactionConflictException — una transazione concorrente sullo stesso Item.
Esempio di codice: TransactWriteItems in Node.js · in Python (boto3) — una transazione condizionata funzionante da adattare.
Impara: DynamoDB transactions · Condition expressions

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.