# Troubleshooting
> Fixes for the problems people actually hit on Ozmium - reverted swaps, failed approvals, odd balances, black screens, and 402 loops on the agent API.
Source: https://docs.ozmium.org/guides/troubleshooting/
Keywords: ozmium troubleshooting, transaction reverted base, insufficient allowance error, defi swap slippage revert, x402 402 loop
Updated: 2026-07-27
---

Most problems fall into a handful of categories. Work down this list before assuming something is
broken.

## Transaction Problems

**"Transaction reverted" on a swap.** Almost always slippage - the market moved past your tolerance
between quote and inclusion. Re-quote and retry, or widen slippage slightly on a thin pair. A revert
costs gas but does not cost principal.

**"Insufficient allowance".** The ERC-20 approval did not land, or it was for less than the action
needs. Approve again. On an injected wallet, approve and action are separate transactions and the
first can silently fail.

**"Insufficient funds for gas".** You spent the ETH you were holding for gas. Keep a small ETH buffer
that you never touch. Every transaction on Base needs it unless a host is sponsoring gas.

**Wrong network.** Ozmium is Base mainnet, chain id 8453, only. If your wallet is on another network,
switch it before anything will work.

**Position opened at a different size than expected.** Check whether you were reading a pending order
as a position. A resting limit or stop order holds collateral but has not filled. They are listed
separately for exactly this reason.

## Balance and Display Problems

**A balance looks wrong.** Check the transaction on [Basescan](https://basescan.org) first. The chain is authoritative and
every interface is downstream of it. If Basescan and Ozmium disagree, Basescan is right.

**A value is showing as unavailable rather than zero.** That is intentional. When a price feed or RPC
read fails, Ozmium keeps the last known-good value and marks it rather than rendering a confident
`$0.00` over a broken read. A fabricated zero in a finance app is worse than a blank.

**A token is missing.** Ozmium discovers tokens from onchain balances. A token with no liquid market
may show a balance without a confident USD valuation, which is correct behavior rather than an
error.

## App Loading Problems

**Black screen or a page that will not load.** The app carries a self-healing recovery path: if a
stale service worker is serving a dead cached bundle, it unregisters every worker, drops every cache,
and reloads once. If you land on a black screen anyway, a hard reload usually clears it. Clearing
site data for ozmium.org is the guaranteed fix.

**Stuck inside a host app.** Opened inside the [Base App](https://base.app/invite/ozbeta/D1H4FT25) or [Farcaster](https://farcaster.xyz/~/code/1914H5), the mini-app host controls the
webview. Close and reopen the mini-app rather than reloading inside it.

## Leverage-Specific

**Liquidated earlier than the displayed price.** The displayed liquidation price excludes rollover
and borrow fees. Those accrue continuously against your margin, so the real liquidation point drifts
closer on a position left alone.

**Stop loss filled worse than set.** In a fast move, the fill can be worse than the stop, or the
position can reach liquidation before the stop executes. A stop tells the venue when to act. The fill is decided by the market.

**Cannot decrease leverage.** Decreasing leverage requires a collateral top-up. Ozmium prepends the
USDC approve, but you still need the USDC.

## Agent-Specific

**Getting HTTP 402 repeatedly.** You are sending the payment header incorrectly, or the signed amount
does not match the challenge. Re-read the challenge in the `PAYMENT-REQUIRED` header and sign that
exact amount. See [x402 Payments](/agents/x402/).

**`bad payTxHash` or `bad burnTxHash`.** The x402 payment is not the authorization for a prop action.
You need a real onchain OZ transfer as well. See [Prop](/guides/prop-desk/).

**Rate limited.** Anonymous traffic has a far lower ceiling than paid traffic. Paying raises it
automatically; there is nothing to request.

**Transaction built by an endpoint reverts on broadcast.** Check that you have not modified the
returned `{ to, data, value }`, that the wallet you are broadcasting from is the wallet the builder
was given, and that any required approval landed first.

## A Market Order that Never Filled

Collateral escrowed against a market order the keeper never filled, usually one placed while that
venue was closed, is recoverable. Ozmium reads pending orders directly from the venue contract and
offers **Reclaim** once the execute timeout passes, which cancels the order onchain and returns the
collateral. Full detail in [Leverage](/guides/leverage/#reclaim-a-stranded-order).

## Reporting Something Broken

When something breaks, the app sends a diagnostic report so it can be fixed: the error, the page, the
app build, and basic browser details such as viewport and connection type. It records which **kind**
of wallet is connected - whether the browser has an injected provider at all - and never your wallet
address, your balance, or any identifier tied to you. Reports are grouped by error, not by person.

If you want a human to look at it, write to **[hello@ozmium.org](mailto:hello@ozmium.org)** or post
in the Discord. Either reaches the same place. Include what you were doing, the transaction hash if
there is one, and roughly when it happened.

The same two channels are where ideas go. If you want a market listed, an endpoint shaped differently,
a view that does not exist yet, or a workflow the app makes harder than it should be, say so. The
roadmap is built from what people ask for, and a specific request from someone actually using the
thing beats any amount of internal guessing.

{{discord}}

Security issues should go through the process in [Security and Trust](/company/security/) instead.

## Related

- [Install as an App](/start/web-apps/) - pinning Ozmium to a home screen, and what a stale build looks like
- [Charts](/guides/charts/) - reading the chart, its indicators, and its signal markers