> For the complete documentation index, see [llms.txt](https://docs.ensemble.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ensemble.io/use-ensemble/transaction-troubleshooting.md).

# Transaction troubleshooting

Diagnose common Ensemble transaction failures without unsafe retries or unverified contract interactions.

A failed transaction usually points to a specific check: the network, approval, amount, limit, or vault status. Read the error before retrying. It helps you fix the right problem and avoid another failed transaction.

| Symptom                  | Check first                                                                       | Safe response                                         |
| ------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Wallet rejected          | User cancellation or wallet policy                                                | Review; do not auto-resubmit                          |
| Wrong network            | Chain ID and verified application                                                 | Switch only to HyperEVM `999`                         |
| Insufficient USDC or gas | Token balance and gas balance                                                     | Fund the correct asset/network                        |
| Allowance failure        | Token, spender, amount                                                            | Approve the verified spender for the selected call    |
| Minimum error            | Route action minimum                                                              | Use a compliant amount or stop                        |
| Hard-max error           | Per-transaction maximum                                                           | Reduce the amount deliberately                        |
| Rolling-cap error        | Protocol, vault, account, or vault-account capacity                               | Wait for capacity; do not bypass attribution          |
| Paused route             | Protocol or vault action pause                                                    | Wait for an official status change                    |
| Zero redemption capacity | Buffer, route, pending work, emergency state, Standard mode, or incompatible read | Identify the cause; never assume shares are worthless |
| Stale display            | Observation block and time; compatible contract reads                             | Re-read on-chain or show unavailable                  |
| Unknown revert           | Simulation and decoded custom error                                               | Stop and escalate with transaction data               |

## Details to keep

Accurate transaction details let support reproduce the failure without access to your wallet. Keep the chain ID, transaction hash, verified contract target, function, amount, decoded error, block number, and observation time. Never share seed phrases or wallet recovery material with support.

## Which record to check first

Start with the source closest to settlement. Use the wallet receipt and deployed contract state first, VaultLens for derived on-chain reads, and contract events for historical explanation.