Troubleshooting

Start with the exact error. Most Anode failures are setup problems: no provider, wrong config file, missing tool, blocked permission, or a daemon address mismatch.

No Provider Configured

Set one provider key:

export ANTHROPIC_API_KEY="..."
anode -x "hello"

Or use OpenAI login:

anode login

If you use a config file, verify Anode is loading the one you expect:

anode config list

Main config uses the first file that loads cleanly in this order:

$ANODE_CONFIG
~/.config/anode/config.json
./anode.json

Wrong Model Or Provider

Model names use provider/model:

anode -x --model openai/gpt-5.5 "hello"
anode -x --model anthropic/claude-sonnet-4-6 "hello"

If Anode says the provider or model was not found, list your configured keys and check Providers. Provider keys from environment variables only fill missing provider config; they do not override a provider key already set in config.

Config File Not Loading

Validate discovery, parsing, duplicate keys, and safety checks. This exits nonzero on failure:

anode config doctor

Successful checks end with Config doctor passed..

Run with a specific config:

ANODE_CONFIG="$PWD/anode.json" anode -x "summarize this repository"

Remember: the main config is not layered. If ~/.config/anode/config.json loads cleanly, ./anode.json is not loaded as the main config unless you point ANODE_CONFIG at it.

If an earlier config file exists but cannot be safely read or parsed, Anode skips it and tries the next candidate. $ANODE_CONFIG errors warn on stderr; run anode config list to see every candidate’s status.

Tool Not Available

List tools:

anode tools list

Show one tool:

anode tools show read

Common causes:

The selected profile hides the tool.
tools.disabled disables the tool.
Web access is disabled.
MCP, toolbox, or plugin tools failed to load.
The lsp tool has no configured or auto-detected language server.

Check a profile-filtered tool list:

anode tools list --profile review

Permission Surprise

Preview the decision without running the tool:

anode permissions test bash --command "go test ./..."
anode permissions test edit_file --path internal/app/app.go
anode permissions test bash --preset careful --command "rm -rf tmp"

Rules are evaluated in this order:

permissions in the main config
First readable project file: .agents/permissions.json, then .anode/permissions.json
permissionPreset

First matching rule wins.

Headless Run Blocks

--approval ask can block when a headless run needs confirmation. Use one of:

anode -x --approval auto "run tests and summarize failures"
anode -x --approval unrestricted "run in a disposable workspace"

For CI, prefer explicit rules and narrow tools:

anode -x --allow-tool read --allow-tool finder --profile find "find risky changes"

Web Tools Do Not Work

Check the environment default:

echo "$ANODE_WEB_ENABLED"

Enable in config:

{
  "web": {
    "enabled": true
  }
}

Disable values for ANODE_WEB_ENABLED are 0, false, no, off, and disabled.

web_search rejects localhost, private IPs, and redirects to them. The same network policy applies when agents fall back to bash + curl for raw page bodies.

MCP Not Loading

Check configured servers:

anode mcp list

Connect and show discovered tools:

anode mcp list --connect

Run diagnostics:

anode mcp doctor

Successful checks end with MCP doctor passed..

Workspace MCP config is not loaded by default. Trust the workspace:

anode mcp trust

Or enable workspace MCP globally in config:

{
  "mcp": {
    "allowWorkspace": true
  }
}

Remote MCP OAuth:

anode mcp oauth status
anode mcp oauth login <server-name> --client-id <client-id>

LSP Tool Missing

Install or configure a language server. Auto-detected servers include:

gopls
typescript-language-server
pyright-langserver
rust-analyzer

Check the binary:

which gopls

Add .lsp.json in the project if the server is not on PATH. See LSP.

Sessions Not Saving

Check config:

{
  "session": {
    "autoSave": true
  }
}

Check the session store:

ls -la ~/.config/anode/sessions

Use a custom store if needed:

{
  "session": {
    "storePath": "/path/to/anode-sessions"
  }
}

Daemon Cannot Be Reached

Start the daemon:

anode daemon

Use a TCP address if a Unix socket is awkward in your environment:

anode daemon --addr 127.0.0.1:7433
anode runs list --daemon 127.0.0.1:7433

For the default socket, Anode uses:

~/.config/anode/daemon.sock

Review Checks Not Running

--checks reads project checks from:

.agents/checks/*.md

Run:

anode review --base main --checks

If no checks run, verify the directory and check file names.