Why did my Sui transaction fail?

A Sui transaction fails in one of two places. It can be rejected before execution: validators refuse to sign it because an input is wrong, an object version is stale, or gas can't be paid. Nothing goes on chain and you pay nothing. Or it can fail during execution: it is ordered and run, but a Move function aborts or the gas budget runs out. Then it's recorded on chain with a failure status and you still pay gas. The error message tells you which case you're in.

Rejected before execution

These come back as an RPC or SDK error, not as a transaction digest:

Message (abridged)	Cause
`Transaction needs to be rebuilt because object ... is unavailable for consumption, current version: N`	You used an old version of an owned object. Rebuild with fresh object references.
`... reserved for another transaction` / `... equivocated until the next epoch`	Two transactions tried to use the same owned object version. See object version and locked object errors.
`Could not find the referenced object ...`	Wrong object ID, wrong network, or the object was deleted.
`Balance of gas object ... is lower than the needed amount`	The gas coin can't cover the budget.
`Gas budget: ... is lower than min` / `higher than max`	Budget outside the protocol limits.
`Gas price ... under reference gas price (RGP)`	Gas price set below the current epoch's reference price.
`No valid gas coins found for the transaction`	No SUI, or the only coin is also used as a transaction input.

Failed during execution

The transaction has a digest and effects with status: failure. Common execution errors:

MoveAbort: a Move assert! or abort fired. The error includes the module, function and abort code. Packages built with Move 2024 clever errors also give the constant name and source line. Look the code up in the package source. See Move error codes.
InsufficientGas: the transaction used up its budget. Raise --gas-budget or let the CLI or SDK estimate it.
UnusedValueWithoutDrop: a PTB produced a value without drop (often a coin) and didn't transfer or consume it. Transfer it, merge it, or pass it to another call.
CommandArgumentError: an argument has the wrong type, or an object was passed by value when the function wants a reference (or the other way round).
InsufficientCoinBalance: a split asked for more than the coin holds.
ExecutionCancelledDueToSharedObjectCongestion: too many transactions wanted the same shared object. Retry, or pay a gas price above the reference price to get priority.

Read the failure

From the CLI, look up any digest:

Terminal

sui client tx-block <DIGEST>

From TypeScript (@mysten/sui v2), execution doesn't throw on an on-chain failure. It returns a FailedTransaction variant:

TypeScript

const result = await client.signAndExecuteTransaction({
  transaction: tx,
  signer: keypair,
  include: { effects: true },
})

if (result.$kind === 'FailedTransaction') {
  const { error } = result.FailedTransaction.status
  console.error(error.message)
  if (error.$kind === 'MoveAbort') {
    console.error(error.MoveAbort.abortCode, error.MoveAbort.location)
  }
}

If you don't set a gas budget, the SDK simulates the transaction while building it and throws a SimulationError when the simulation fails. Its executionError field has the same structured error. In that case nothing was sent, which is also how the CLI reports "Dry run failed, could not automatically determine a budget".

Debugging steps

Check that you're on the network you think you are (sui client active-env). IDs from testnet don't exist on mainnet.
Simulate the transaction with --dry-run or simulateTransaction() to see the error without paying gas.
For a Move abort, find the abort code in the module's source.
To step through a transaction that already ran, replay it locally with sui replay and the Move debugger.
Check whether a gas budget problem is hiding the real error.

You can try transactions on testnet without setting up anything in the site's playground.

Sources

Troubleshooting Common Errors, Sui documentation
Executing Transactions, Sui TypeScript SDK docs
execution_status.rs and error.rs, MystenLabs/sui on GitHub
Gas in Sui, Sui documentation