DynamoDB TransactionCanceledException — ConditionalCheckFailed

요약 — TransactWriteItems가 취소되었고 CancellationReasons 배열에 ConditionalCheckFailed 항목이 있습니다. 트랜잭션의 조건 표현식 중 하나가 성립하지 않아 DynamoDB가 모든 작업을 원자적으로 롤백했습니다. reasons 배열을 읽으세요 — 항목들은 위치 기반이며 요청 항목당 하나씩입니다 — 어느 항목의 조건이 실패했는지 찾은 다음 그 항목의 전제 조건이나 데이터를 고치세요.

무엇을 의미하나요

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

TransactWriteItems는 전부 아니면 전무입니다. 단일 작업의 ConditionExpression이 false로 평가되면 DynamoDB는 전체 요청을 취소하고 항목별 이유 목록을 보고합니다. 위치 i 의 ConditionalCheckFailed는 i 번째 항목의 조건이 충족되지 않았다는 뜻입니다 — 트랜잭션은 부분적으로도 적용되지 않았습니다.

왜 발생하나요

낙관적 잠금 실패 — 다른 작성자가 이미 항목을 변경하거나 생성해 version = :v / attribute_not_exists(pk) 가드가 실패했습니다.
고유성 가드 발동 — attribute_not_exists(pk) 삽입이 경합에서 져서 항목이 이미 존재합니다.
오래된 읽기 — 이후 변경된 값으로 조건이 구성되었습니다.
이유 목록 오독 — 배열은 위치 기반이며 TransactItems처럼 정렬됩니다. 슬롯의 None은 그 항목이 괜찮았다는 뜻이고, ConditionalCheckFailed는 실패한 항목을 표시합니다. (배열의 다른 코드 — TransactionConflict, ItemCollectionSizeLimitExceeded, ProvisionedThroughputExceeded, ThrottlingError, ValidationError — 는 다른 의미입니다.)

어떻게 고치나요

예외의 CancellationReasons를 검사하고 ConditionalCheckFailed가 있는 인덱스를 찾으세요 — 그것이 실패한 작업입니다.
항목을 다시 읽고 결정하세요: 새 전제 조건으로 재시도(낙관적 잠금 재시도 루프)하거나 호출자에게 충돌을 표시합니다.
조건이 잘못되었다면 고치세요 — 예: 정당하게 이미 존재하는 항목에 대한 attribute_not_exists(pk).
실패한 작업에 ReturnValuesOnConditionCheckFailure: ALL_OLD를 추가하세요 — DynamoDB가 조건을 깨뜨린 항목을 반환하도록(디버깅에 유용).
재시도를 제한하세요 — 지속적으로 실패하는 조건은 일시적 오류가 아니라 실제 비즈니스 충돌입니다. 영원히 재시도하지 마세요.

실패한 트랜잭션을 수동으로 디버깅하나요? 재시도하기 전에 DynoTable 데스크톱 앱에서 현재 항목 상태를 검사해 전제 조건이 성립하지 않은 이유를 정확히 확인하세요.

FAQ

트랜잭션의 어느 항목이 실패했는지 어떻게 아나요? TransactionCanceledException의 CancellationReasons 배열을 읽으세요. 위치 기반입니다 — 요청 항목당 하나씩, 순서대로입니다. 코드가 ConditionalCheckFailed인 항목이 조건 표현식이 false로 평가된 작업을 식별합니다. 코드가 None인 항목은 성공했습니다.

트랜잭션 내부의 ConditionalCheckFailed는 재시도할 수 있나요? 자동으로는 아닙니다. 이는 일시적 오류가 아니라 실제 전제 조건 충돌입니다. 항목을 다시 읽고, 쓰기가 여전히 적용되는지 결정한 다음 새 조건으로 재시도하세요 — 또는 사용자에게 충돌을 표시하세요.

References

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

DynamoDB TransactionCanceledException — ConditionalCheckFailed

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

FAQ

관련 오류

References