Troubleshooting - Circuit

CLI and session admission

Symptom	Action
`circuit: command not found`	Install with `bun install -g @circuitorg/agent-cli`.
`circuit run` or `circuit unwind` reports that `--wallet` is required	Pass the wallet name or address: local for embedded execution, hosted for `--target hosted-engine` and `--target hosted`.
A repeated Start or Top-up returns `409`	Reuse its request key with identical inputs. A changed wallet, allocation, settings, attachment, driver or test mode needs a new request. Replay requires pinned admission inputs.
Top-up succeeded but its run has not started	Admission commits allocation and a queued run together. Earlier execution and pause delay that run; at most one run executes per session. Inspect its returned run ID.

SDK failures and state

Symptom	Action
A method throws `ApiError`	Methods return data directly and throw on failure. Log the error with `agent.log(message, { error: true })` and rethrow unless the strategy can safely handle it. See error handling.
Memory does not persist	Store strings: `agent.memory.set({ key: "count", value: "5" })`; serialize objects with `JSON.stringify`.
Holdings do not change after a transaction	`agent.allocation` stays fixed during an invocation. Track dependent effects locally; the next invocation receives fresh committed state. Do not cache balances across runs.
`EDGE_502` or `EDGE_504`	The edge failed to return an engine response; admission may have happened. Preserve the operation ID, inspect its resource and never resubmit automatically.

Swaps

Symptom	Action
”No routes found”	Check token addresses, liquidity and network IDs: use `ethereum:137`, not `polygon`.
”Price impact is too high”	The upstream swap provider rejected the route for excessive price impact. Review the trade amount and available liquidity.
Incorrect amounts	Use smallest-unit strings: one six-decimal USDC is `"1000000"`; Core USDC on `hypercore` has eight decimals.

Venue errors

Symptom	Action
Hyperliquid rejects an order below 10 quote units	The floor uses size times limit price. Only a `reduceOnly` order closing the wallet’s entire live position is exempt. Copy the exact `quantity` from the `kind: "perp"` row of `agent.allocation.holdings`; never round a reduction.
Hyperliquid rate limiting	Hyperliquid market data comes from the hosted `agent.data` feeds, which serve indexed observations rather than a venue call per read. Invocation-start collateral and positions are already in `agent.allocation`.
Post-only, stop or take-profit order rejected	An `alo` order that would cross is rejected; use `gtc` or move the price. Hyperliquid trigger orders are unsupported.
Polymarket `market_order` says “Something went wrong”	Insufficient asks/bids can cause the CLOB’s `calculateBuyMarketPrice` to return a generic 500. Check book depth, especially near extreme outcome prices.
”No orderbook exists for the requested token id”	Verify the outcome-token `asset` against Polymarket’s API.

Validate with circuit check before uploading. Use console output for developer diagnostics, pin dependencies, and choose schedules within provider rate limits.