TransactionCanceledException: Transaction cancelled, please refer cancellation reasons for specific reasons [ConditionalCheckFailed, None]

What it means

A DynamoDB transaction is all-or-nothing across up to a hundred items. If any single operation cannot proceed, the entire transaction is cancelled and nothing is written. TransactionCanceledException reports that, and its message is deliberately vague because the detail lives somewhere the message cannot reach.

That detail is the CancellationReasons array on the exception object, and it is positional: one entry per item you submitted, in the order you submitted them. An entry of None means that operation was fine. Anything else names both what went wrong and — through its index — exactly which of your operations caused the rollback. In a transaction of one item that is barely useful; in a transaction of twelve it is the difference between a diagnosis and a guess.

The trap is that most logging never captures it. console.error(error) and str(e) print the message, and the message is the sentence telling you to consult reasons you did not print. Teams routinely run for months with logs full of "please refer cancellation reasons" and no way to refer to them. Logging the array is a one-line change and it is almost always the right first move.

The reason codes also split cleanly into two groups that want opposite responses. ConditionalCheckFailed is deterministic: something about the data did not match what you required, and retrying the identical transaction produces the identical cancellation. TransactionConflict and ProvisionedThroughputExceeded are transient: another writer was in the way, or capacity was momentarily short, and a retry will very likely succeed. Retrying the first wastes capacity and inflates duration; not retrying the second turns ordinary contention into a failed request. Both look the same from outside the array.

One capacity note worth carrying: a transaction consumes about twice the write capacity of the same operations issued individually, because DynamoDB performs a prepare phase and a commit phase. A table provisioned comfortably for normal traffic can start throttling when the same volume of work moves into transactions, which then surfaces here as a cancellation rather than as a throughput error you would recognise.

What it looks like in CloudWatch

This is the shape the failure arrives in: the lines of one invocation scattered among everything else the log group received at the same moment.

The panel on the right is generated by running the excerpt on the left through the same parser that powers the free web stitcher — it is what the tool actually produces for this input, not an illustration of it.

How to confirm it from the logs

Read the reasons array, and read it positionally. [ConditionalCheckFailed, None] means the first item in your transaction failed its condition and the second was fine. [None, None, TransactionConflict] means the third item was being written by another transaction at the same moment. The array is in the same order as the items you submitted, which is what lets you map a reason back to a specific operation.

The reason code also decides whether to retry. ConditionalCheckFailed is deterministic — retrying the identical transaction fails identically. TransactionConflict and ProvisionedThroughputExceeded are transient and usually succeed on a second attempt.

The message alone is nearly useless, and many logging setups print only the message. If your logs show the sentence without the array, the first fix is to log the array.

Causes, most likely first

Fixes

jstry {
  await client.send(new TransactWriteItemsCommand({ TransactItems: items }));
} catch (error) {
  if (error.name === "TransactionCanceledException") {
    console.error("transaction cancelled", {
      reasons: error.CancellationReasons?.map((reason, index) => ({
        index,
        code: reason.Code,
        message: reason.Message
      }))
    });
  }
  throw error;
}

jsconst RETRYABLE = new Set([
  "TransactionConflict",
  "ProvisionedThroughputExceeded",
  "ThrottlingError"
]);

function shouldRetry(error) {
  return error.name === "TransactionCanceledException"
    && error.CancellationReasons?.some((reason) => RETRYABLE.has(reason.Code));
}

js// Two operations on one key cancel the whole transaction.
const byKey = new Map();
for (const operation of operations) {
  byKey.set(`${operation.pk}#${operation.sk}`, operation);
}
const items = [...byKey.values()];

Also seen as

The same underlying failure, worded differently by a different runtime, SDK version, or logging layer. All of these land here — there is no separate page for each phrasing.

Related errors

Errors that show up alongside this one, or that people mistake for it.

References

• Amazon DynamoDB Developer Guide — Handling transaction errors
• Amazon DynamoDB Developer Guide — Transaction conflict handling