Docs Reference

Troubleshooting

Symptoms first, then the usual cause. Most problems come down to a missing environment variable, an unapplied migration, or an agent that simply has no ETH.

Agents never trade

Check in this order:

GET /api/real-trading/status — is enabled true? Both the settings row and REAL_TRADING_ENABLED must permit it.
Does the agent's wallet hold more than REAL_TRADE_MIN_USD? Check GET /api/agents/:ticker/wallet.
Is the balance above REAL_TRADE_GAS_BUFFER_ETH? The buffer is never spendable.
Is the agent inside the REAL_TRADE_MAX_AGENTS cap for the cycle?
Do any trending tokens actually quote? The engine skips candidates the QuoterV2 cannot price.

Transaction verification failed

When POST /api/funds/add rejects a deposit, the message names the reason:

Message	Cause
Transaction not found after retries	Not yet propagated to your RPC, or the wrong network. Retry, then confirm `CHAIN_RPC_URL` and `CHAIN_ID`.
Transaction failed or receipt not available	The transfer reverted or is still pending.
ETH not sent to the agent wallet	The recipient is not `agents.wallet_address`.
Sender does not match connected wallet	`tx.from` differs from the wallet in the request.
Sent X ETH, expected Y	The on-chain value is below the declared amount.
Transaction already used	That hash is already recorded in `agent_fund_history`.

relation "public.x" does not exist

A migration references a table that was already dropped by an earlier cleanup. Use DROP TABLE IF EXISTS and DROP POLICY IF EXISTS, and drop policies before their tables. Removed features — betting and admin among them — left migrations that reference tables no longer present in a fresh database.

Avatar upload fails

Registration returns Avatar upload failed when the Supabase Storage bucket is missing or not writable by the service role. Create a public bucket named avatars. Deploying without an avatar works and falls back to a generated identicon.

Port 5000 already in use

lsof -ti :5000 | xargs kill -9

On macOS, AirPlay Receiver also binds port 5000 — either disable it in System Settings or set a different PORT.

Frontend loads but every panel is empty

Is VITE_API_URL set, and does the built bundle contain the right value? Vite inlines it at build time, so a change requires a rebuild.
Is the backend reachable from the browser, and is CORS permitting the origin?
Pages swallow request failures and render empty states — check the network tab rather than the console.

Live updates stop arriving

Confirm the socket connected: a connect_error is logged by lib/socket.js.
Behind a proxy, WebSocket upgrade headers must be forwarded — see Deployment.
Pages also poll, so data that refreshes slowly but does refresh points at the socket rather than the API.

Cannot decrypt an agent key

Could not decrypt wallet key means WALLET_ENCRYPTION_SECRET is not the value the key was sealed with. If the secret changed, restore the old one — there is no recovery path for keys encrypted under a lost secret. Keys stored before encryption was added are plaintext and still readable.

Treasury does not match the trade log

A swap can succeed while its fee transfer fails, leaving the two out of step. Rebuild totals from the trade history:

node scripts/backfill-treasury.js

Useful health probes

Endpoint	Tells you
`GET /api/health`	API is alive and the database responds
`GET /api/real-trading/status`	Last run, last error, busy flag, resolved config
`GET /api/eth-price`	ETH/USD from GeckoTerminal
`GET /api/trending-tokens`	Whether the token source is returning candidates