> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues, gotchas, and solutions when building and testing Circuit agents.

### CLI Issues

**`circuit: command not found`**

The CLI is not installed globally. Install with:

```bash theme={null}
bun install -g @circuitorg/agent-cli
```

**`circuit run --hosted engine` fails with "No wallet found"**

Hosted runs select wallets from your Circuit account, not from the local
keystore. Create or import a wallet in the Circuit app first, then rerun:

```bash theme={null}
circuit run --hosted engine
```

In non-interactive environments, pass `--wallet` with the hosted
wallet address or name shown in the app.

**`circuit run` fails immediately**

Ensure dependencies are installed before running:

* TypeScript: `bun install`
* Python: `uv sync`

***

### SDK Issues

**`result.data` is undefined**

Always check `success` before accessing `data`:

```typescript theme={null}
const result = await agent.swap.quote({...});
if (result.success && result.data) {
  // Safe to use result.data
} else {
  await agent.log(result.error || "Request failed", { error: true });
}
```

**Memory values are not persisting**

Memory values must be **strings**. If you're storing numbers or objects, serialize them first:

```typescript theme={null}
// Wrong
await agent.memory.set("count", 5);

// Correct
await agent.memory.set("count", "5");
await agent.memory.set("config", JSON.stringify({ threshold: 0.05 }));
```

**Holdings don't update after a transaction**

`agent.portfolio` is a snapshot taken at the start of execution and does not refresh mid-cycle. Track the changes you make in [Memory](./sdk-reference/memory) if you need updated state within the same `run`.

***

### Swap Issues

**Quote fails with "no routes found"**

The token pair or route is not supported by any routing engine. Verify:

* Token addresses are correct for the specified network
* Network identifiers are valid (e.g., `"ethereum:137"` not `"polygon"`)
* The route exists (some token pairs have no liquidity)

**Quote fails with "Price impact is too high"**

The swap amount is too large relative to available liquidity. Reduce the amount or increase slippage tolerance. Circuit automatically filters quotes with >100% price impact.

**Swap amounts seem wrong**

Amounts are in **smallest units** (wei, lamports, etc.), not formatted values. For example, 1 USDC on typical EVM token contracts (6 decimals) = `"1000000"`, not `"1"`. For Hyperliquid `hypercore:perp` starting-asset USDC, Circuit uses **8** decimal places (e.g. 1 USDC = `"100000000"`); see [Hyperliquid](./sdk-reference/hyperliquid).

**Omit `fromToken`/`toToken` for native tokens** — don't pass the zero address.

***

### Hyperliquid Issues

**`Unknown perp asset` error**

Perp coins are just the base asset: `"BTC"`, `"ETH"`. Do NOT use `"BTC/USDC"` for perps — that format is for spot only.

**`Unknown spot pair` error**

Spot coins must include the quote: `"BTC/USDC"`, `"ETH/USDC"`. Do NOT use just `"BTC"` for spot.

**Rate limiting**

Hyperliquid rate-limits aggressively. **Avoid calling `balances()` or `positions()` in loops.** Call them once at the start of your `run` function and reuse the results.

**`stop` or `take_profit` order fails**

Stop and take-profit orders require a `triggerPrice` parameter. This is separate from the `price` parameter (which acts as a slippage limit).

***

### Polymarket Issues

**`market_order` returns "Something went wrong"**

This usually means the order book has insufficient liquidity for your order size. The CLOB's `calculateBuyMarketPrice` throws a generic error when there aren't enough asks (for buys) or bids (for sells), which surfaces as a 500 error.

**Fix:** Always check order book liquidity before placing orders:

```python theme={null}
import requests

def check_order_book_liquidity(token_id: str, side: str, min_usd: float) -> bool:
    response = requests.get(
        "https://clob.polymarket.com/book",
        params={"token_id": token_id},
        timeout=10,
    )
    if not response.ok:
        return False
    book = response.json()
    orders = book.get("asks" if side == "BUY" else "bids", [])
    total_usd = sum(float(o["price"]) * float(o["size"]) for o in orders)
    return total_usd >= min_usd
```

Also filter out markets with extreme prices (below 0.10 or above 0.90) — these typically have thin liquidity.

**`No orderbook exists for the requested token id`**

The `tokenId` is invalid or the market doesn't exist. Verify the token ID from Polymarket's API.

**Dust positions after selling**

Polymarket has different decimal precision for buys and sells, which can leave small residual positions. Clean these up with `redeemPositions({ tokenIds })` after market expiry.

***

### Python-Specific Issues

**`from` keyword conflict in swap.quote()**

See [Swap: Python `from` Parameter](./sdk-reference/swap#python-from-parameter) for the full workaround.

**Python SDK uses snake\_case**

Use snake\_case keys when passing dicts to SDK methods. The SDK converts to camelCase internally when calling the API:

```python theme={null}
response = agent.sign_and_send({
    "network": "ethereum:1",
    "request": {
        "to_address": "0x...",
        "data": "0x",
        "value": "100000000000000",
    }
})
if response.success and response.data:
    agent.log(f"Sent: {response.data.tx_hash}")
```

***

### General Tips

* **Test locally first** with `circuit run` before uploading
* **Use `debug: true` / `debug=True`** for verbose logging that won't appear in the user-facing UI
* **Check `executionMode`** if your agent behaves differently in auto vs manual mode
* **Pin dependency versions** in `pyproject.toml` / `package.json` to avoid breaking changes on deploy
* **Keep `runtimeIntervalMinutes` reasonable** — too frequent runs may hit rate limits on external APIs