Skip to main content

Troubleshooting

Diagnostics First

Before digging into specific issues, run the built-in diagnostics command:

npx web3agent doctor --json

This checks your Node.js version, environment variables, wallet configuration, and integration health. The JSON output is useful for sharing with maintainers when reporting bugs.

You can also call the server_status tool from within any MCP client to see which integrations are loaded and what the active configuration looks like.

Node.js Version Too Old

Symptom: Error like SyntaxError: Unexpected token or ERR_UNSUPPORTED_ESM_URL_SCHEME on startup.

Cause: web3agent requires Node.js 22 or later. Older versions don't support the ESM features it uses.

Fix:

node --version  # check current version

If it's below 22, update via nodejs.org or use a version manager:

# Using nvm
nvm install 22
nvm use 22

# Using fnm
fnm install 22
fnm use 22

Tool Not Found

Symptom: MCP client reports a tool doesn't exist, or server_status doesn't show an expected integration.

Cause: The integration that provides the tool may not have loaded. This usually happens when a required API key is missing or an optional plugin wasn't activated.

Fix:

  1. Call server_status to see which integrations are active.
  2. Check that the relevant API key is set (e.g., ZEROX_API_KEY for 0x tools, COINGECKO_API_KEY for CoinGecko tools).
  3. Restart the MCP server after adding the key.
# Check what's loaded
# (call server_status tool from your MCP client)

# Then verify your env
echo $ZEROX_API_KEY
echo $COINGECKO_API_KEY

Write Operation Failed: No Wallet

Symptom: Error WALLET_NOT_CONFIGURED or WALLET_NOT_ACTIVE when trying to swap, transfer, or write to a contract.

Cause: Write operations require an active wallet with a private key.

Fix:

Set PRIVATE_KEY or MNEMONIC in your environment:

PRIVATE_KEY=0xabc123...

Or generate a new wallet via the CLI:

npx web3agent init

Then activate it with the wallet_activate tool.

Write Operation Queued, Not Executing

Symptom: A swap or transfer returns a confirmation ID but never executes.

Cause: CONFIRM_WRITES=true (the default). Operations are queued and wait for explicit confirmation.

Fix:

Call transaction_confirm with the returned confirmation ID from your MCP client. The AI agent should prompt you to do this.

If you want operations to execute immediately without confirmation (for autonomous agents), set:

CONFIRM_WRITES=false

Consider enabling the policy engine if you disable confirmation:

POLICY_ENABLED=true
POLICY_MAX_SINGLE_TX_USD=100
POLICY_MAX_DAILY_USD=500

Chain Not Supported

Symptom: Error CHAIN_NOT_SUPPORTED when specifying a chain ID.

Cause: The chain ID isn't in web3agent's supported list.

Fix: Check the supported chains list. The 17 supported chain IDs are:

1, 8453, 42161, 10, 137, 59144, 56, 43114, 324, 534352, 34443, 81457, 5000, 42220, 100, 11155111, 84532

If you need a chain that isn't listed, open a feature request on GitHub.

Blockscout Error on Unsupported Chain

Symptom: BLOCKSCOUT_NOT_SUPPORTED error when calling a blockscout_* tool.

Cause: Blockscout indexer tools only work on 8 chains: Ethereum, Base, Arbitrum, Optimism, Polygon, Gnosis, Scroll, zkSync Era.

Fix: Switch to an evm_* tool for live on-chain reads, which work on all 17 chains. For example:

  • Instead of blockscout_get_address_info → use evm_get_balance
  • Instead of blockscout_get_transaction → use evm_get_transaction

Or switch to a chain that has Blockscout support.

Policy Rejected

Symptom: Error POLICY_REJECTED with a message about exceeding limits.

Cause: The transaction would exceed POLICY_MAX_SINGLE_TX_USD or POLICY_MAX_DAILY_USD.

Fix:

Check current spend with the policy_get tool. Then either:

  • Reduce the transaction size to fit within limits.
  • Increase the limits in your environment:
POLICY_MAX_SINGLE_TX_USD=1000
POLICY_MAX_DAILY_USD=5000
  • Wait until the next calendar day if the daily limit is exhausted.

RPC Error / Transaction Failing

Symptom: RPC_ERROR, timeout errors, or transactions failing to broadcast.

Cause: The built-in public RPC endpoint may be rate-limited, congested, or temporarily unavailable.

Fix:

Set a private RPC endpoint for the chain you're using:

CHAIN_ID=8453
RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_KEY

Good options for private RPCs:

  • Alchemy — free tier available
  • Infura — free tier available
  • QuickNode — free tier available
  • Ankr — free public endpoints with higher limits

Swap Quote Returns No Results

Symptom: SWAP_QUOTE_FAILED or INSUFFICIENT_LIQUIDITY from Orbs tools.

Cause: Several possible reasons:

  • The token pair has no liquidity on the selected chain.
  • The trade amount is below the minimum (~$6-10 for Liquidity Hub).
  • The token address is incorrect.

Fix:

  1. Verify the token addresses are correct for the chain you're using.
  2. Try a larger amount (at least $10 equivalent).
  3. Try a different chain where the pair has more liquidity.
  4. Use resolve_token to confirm the token is recognized before quoting.

Debug Logging

All web3agent modules write diagnostic output to stderr with a [module-name] prefix. To capture it:

npx web3agent server 2>debug.log

Or pipe it to your terminal while running:

npx web3agent server 2>&1 | tee debug.log

Look for lines starting with [error], [warn], or the specific module name (e.g., [orbs], [lifi], [wallet]) to find the root cause.

Getting Help

If none of the above resolves your issue:

  1. Run npx web3agent doctor --json and copy the output.
  2. Open an issue at github.com/Apegurus/web3agent/issues.
  3. Include the doctor output, the error message, and the steps to reproduce.