Troubleshooting
symptom, cause, fix.

01Diagnose first: where to look

AXIS logs through one class, Logger (lib/utils/logger.dart). Lines start with INFO:, WARN: or ERROR:. They are printed in debug builds only; a release build stays silent, except for FATAL: lines when the app could not start. Long key-like strings (private keys, seed phrases) are replaced with [REDACTED] before printing.

flutter run -d chrome                      # debug build, logs in this terminal
flutter run -d chrome --dart-define=HYPERLIQUID_NETWORK=testnet
flutter logs                               # logs from a connected phone or emulator

The status bar

On wide screens the bottom bar of the terminal is a live health readout (lib/screens/axis_chrome.dart):

DevTools Network tab (web)

Open DevTools → Network, reload, and filter by hyperliquid, config or arbitrum. A red row shows the failing request; its Status column and the Console say why (CORS, 4xx, 5xx, blocked by an extension). The WebSocket appears under the WS filter as wss://api.hyperliquid.xyz/ws; its Messages tab should show frames arriving.

02Hyperliquid API and WebSocket

Endpoints are fixed per network in lib/core/hyperliquid/hyperliquid_env.dart: mainnet https://api.hyperliquid.xyz (/info, /exchange, wss://api.hyperliquid.xyz/ws), testnet https://api.hyperliquid-testnet.xyz. Operator console → Network lists the ones your build is using.

Check that the info endpoint answers from your machine. A healthy answer is HTTP 200 and JSON starting with {"universe":[:

curl -s -o /dev/null -w "%{http_code}\n" -X POST https://api.hyperliquid.xyz/info \
  -H 'Content-Type: application/json' -d '{"type":"meta"}'
# testnet
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://api.hyperliquid-testnet.xyz/info \
  -H 'Content-Type: application/json' -d '{"type":"meta"}'

Both returned 200 when these docs were written.

03Order and signature rejections

Every order is signed on the device (lib/core/hyperliquid/hyperliquid_signer.dart): exchange actions with Hyperliquid's EIP-712 "phantom agent" scheme (chain id 1337, source a on mainnet, b on testnet), approvals and withdrawals as user-signed EIP-712 messages that carry hyperliquidChain = Mainnet or Testnet. Both are derived from the same network setting as the endpoints, so a build cannot sign for one network and send to the other.

04Builder fee not arriving

Open Earnings and press RECHECK: it is the read-only status of routing, the on-chain approval, the rate and the builder balance (every line explained). Then work down this list.

1. Is a builder code configured at all?Earnings title NO BUILDER CODE means the fee is off, the address is empty or malformed, or the rate is 0 or above 100. The log says WARN: HL builder fee config ignored (invalid address or fee N tenths-bps; allowed 1..100).
2. Did this wallet approve the rate?MAX BUILDER FEE ON CHAIN must be at least FEE THIS BUILD CHARGES. Otherwise the log shows WARN: HL builder dropped: approval A < fee F tenths-bps — order placed without the app fee, and the trader is asked to approve at the next order. If the approval request itself failed, the trader saw Fee approval failed (…). Placing the order without the app fee. and the log has HL approveBuilderFee rejected or HL approveBuilderFee failed. Check the approval from a terminal with the maxBuilderFee query in Accounts you must arrange.
3. Did the approval lookup fail?UNKNOWN on Earnings and WARN: HL maxBuilderFee failed, trading without builder: … in the log. Usually a temporary API or rate-limit problem; the order went out without the code.
4. 100 USDC of perps collateral?Hyperliquid does not pay a builder address holding less. Prerequisites → BUILDER PERPS COLLATERAL shows the live value against ≥ 100 USDC. Spot balance and USDC on Arbitrum do not count.
5. Account modePrerequisites → CURRENT MODE shows what the venue reports for the builder address. The requirement shown is standard mode. WARN: HL userAbstraction(…) failed means the check could not be read.
6. Rate above the cap?Perps builder fees above 0.1 % (100 in AXIS units) are rejected by the venue. AXIS refuses such values before sending, so the order goes out without a code rather than failing.
7. Set only on your device?Values typed in the operator console reach only that device. Your users need the values in your published config (why).

05Bridge deposits and withdrawals

A deposit is a plain USDC transfer on Arbitrum One (chain id 42161) to Hyperliquid's Bridge2 contract, which credits the sender's Hyperliquid account. The addresses and the minimum are in lib/core/hyperliquid/hyperliquid_env.dart and shown under Operator console → Network → DEPOSIT BRIDGE.

• Native USDC only. The token at 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 on Arbitrum. Bridged USDC.e is not credited.
• Minimum 5 USDC (minDepositUsdc). Smaller amounts are not credited by the bridge, and the app refuses them with Minimum deposit is 5 USDC.
• ETH on Arbitrum for gas. The transfer is an Arbitrum transaction paid by the sender. Without ETH the transfer fails with Deposit transfer failed: ….
• Mainnet builds only. The deposit always moves real USDC on Arbitrum One, so a build on testnet refuses it with Perps deposits are only available on a mainnet build (HYPERLIQUID_NETWORK=mainnet). Refusing to send real USDC to a non-mainnet bridge address. (lib/features/perps/perps_wallet_config.dart). On testnet, fund the account from Hyperliquid's testnet faucet instead.

06RPC failures (Arbitrum)

Hyperliquid itself needs no RPC. Arbitrum does: the wallet's balances on Arbitrum and the deposit transfer use the Arbitrum RPC endpoints in lib/core/chains.dart (a public primary endpoint and two public fallbacks).

1. Test the endpointA healthy answer is {"jsonrpc":"2.0","id":1,"result":"0xa4b1"} (42161 in hex).

   curl -s -X POST https://arb1.arbitrum.io/rpc -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

2. Look in the Network tabFilter by the RPC host. 429 or 403 means the public endpoint is rate-limiting you.
3. Use your own providerAdd a provider endpoint under Account → Networks on a device, or change the defaults in lib/core/chains.dart and rebuild for everyone (why a paid provider for production).

07Remote config.json not loading

The URL is the constant kAxisAdminConfigUrl in lib/core/config/axis_identity.dart (read through kAdminConfigUrl in lib/core/config/app_config.dart). It ships empty, which disables the hosted channel.

1. Is the URL compiled in?Set it, then rebuild. A hot reload or an edit of the hosted file does not change the address.
2. Does it answer?Expect 200 and a JSON object:

   curl -s -i https://<your-domain>/config.json | head -20

3. CORS (web only)If the file is on a different origin from the terminal, the response must carry an Access-Control-Allow-Origin header that allows your terminal's origin. Check for it:

   curl -s -I -H 'Origin: https://<your-terminal-domain>' https://<your-domain>/config.json

   A missing header shows in the browser Console as a CORS error, and in the log as WARN: [HttpAdminConfig] fetch failed – ….
4. Read the logINFO: [HttpAdminConfig] fetched fresh config from … (maintenance=…, feeBps=…) means it worked. WARN: [HttpAdminConfig] HTTP 404 from … names the status. A fetch slower than 8 seconds times out.
5. Overridden on this device?In Operator console, a value tagged OPERATOR outranks the file. Press CLEAR next to it.
6. Cold startThe app shows its cached copy at start and fetches in the background, so changes appear on the next cold start.

08Firebase

09WalletConnect

10Build and run

11Still stuck?

See Support. Include the version, the platform, the output of flutter --version, the exact command, the full error text and the relevant WARN: lines from a debug run. Remove addresses you do not want to share, and never send a recovery phrase or private key.