Troubleshooting
Common issues and their solutions when setting up or using HyperDex.
Health check shows activeMakers: 0
Why: The Maker SDK is not connected to the backend WebSocket.
Fix: Ensure the SDK is running (npm run dev <name> in maker-sdk/). Check that MAKER_API_KEY and BACKEND_WS_URL in credentials/<name>.cred are correct. Check the SDK terminal for connection error logs.
"No bids received" after the 30-second auction
Why: The maker did not send a bid. Usually the SDK is offline, the pool has zero balance for that token, or the drift guard paused quoting (ghost price >3% from the live oracle mid).
Fix: Check maker-sdk terminal logs. Query the /api/makers/<address>/inventory endpoint and deposit if zero. If drift-paused, press Ctrl+R to re-price.
Dashboard shows "SDK Offline" but the SDK terminal is connected
Why: Idle WebSocket connections drop on hosted backends; the SDK auto-reconnects and the backend now guards the reconnect race so the live socket stays registered.
Fix: Usually self-heals within seconds. If it persists, restart the SDK (Ctrl+C, then npm run dev <name>).
Custom --engine did not load
Why: The engine path is wrong or the file does not export getLevels/getQuote.
Fix: Fix the path and keep the -- separator (npm run dev <name> -- --engine=./x.ts). The SDK falls back to the built-in engine and logs why, so check the banner Engine: line.
Freighter shows "Transaction Failed"
Why: The quote expired (30-second quote window elapsed) or the pool balance was drained between auction and settlement.
Fix: Accept quotes faster. If pool balance is the issue, deposit more inventory.
"Wrong network detected" banner / Freighter not connecting
Why: Freighter is set to a network other than Mainnet.
Fix: Open Freighter → Settings → Network → select Mainnet (Public), then reconnect.
"Maker not registered" error on /maker page
Why: Your wallet address is not in the pool_registry contract.
Fix: Complete the on-chain registration step — paste your signer public key and call register_maker via the /maker UI.