Troubleshooting

Use this page to isolate where a failure lives. Start with the smallest surface that proves the most: local CLI first, then gateway, then WebUI or chat apps.

Fast Diagnosis Order

Run these in order:

nanobot --version
nanobot status
nanobot agent -m "Hello!"

Then, only if the CLI works:

nanobot gateway

This separates failures into layers:

If nanobot agent -m "Hello!" fails, fix that before debugging WebUI, Telegram, Discord, Docker, systemd, or any chat app.

How to Read nanobot status

nanobot status does not call a model. It only checks whether nanobot can find the default config, default workspace, active model or preset, and provider setup summary.

The output has this shape:

nanobot Status

Config: /path/to/config.json ✓
Workspace: /path/to/workspace ✓
Model: provider/model-name (preset: primary)
Provider A: not set
Provider B: ✓
Local Provider: ✓ http://localhost:11434/v1
OAuth Provider: ✓ (OAuth)

Read it like this:

If nanobot status looks right but nanobot agent -m "Hello!" fails, the install and config paths are probably fine. Continue with Provider and Model Problems.

Installation Problems

Use the same Python command for install checks and module fallback. On macOS/Linux that may be python3; on Windows it may be python or py.

Config Problems

Default config path:

~/.nanobot/config.json

Default workspace path:

~/.nanobot/workspace/

nanobot status reads the default config. Use explicit paths on commands that support them when debugging multiple instances:

nanobot agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"
nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace

Common config mistakes:

To refresh missing defaults without overwriting existing settings, run:

nanobot onboard

When prompted about overwriting the config, choose the option that keeps current values and merges missing defaults.

Provider and Model Problems

First prove the provider in the CLI:

nanobot agent -m "Hello!"

Then compare your config against providers.md.

If you need a known-good snippet instead of diagnosis, use provider-cookbook.md.

Langfuse Problems

Langfuse tracing is optional and controlled by environment variables.

See configuration.md#langfuse-observability for setup commands.

Gateway Problems

nanobot gateway is required for WebUI, chat apps, heartbeat, Dream, and long-running channel connections.

Default ports:

Common gateway checks:

nanobot gateway --verbose

WebUI Problems

The packaged WebUI is served by the WebSocket channel.

Minimal config:

{
  "channels": {
    "websocket": {
      "enabled": true
    }
  }
}

Then run:

nanobot gateway

Open:

http://127.0.0.1:8765

If accessing from another device, bind the WebSocket channel to 0.0.0.0 and set token or tokenIssueSecret. The WebSocket channel refuses public binds without a token or token issue secret.

See webui.md#lan-access for LAN setup and ../webui/README.md for frontend development.

Chat App Problems

Before debugging a chat app:

nanobot agent -m "Hello!"
nanobot channels status
nanobot gateway

Then check:

See chat-apps.md for channel-specific setup.

Tool and Workspace Problems

Memory and Session Problems

Collect Useful Evidence

When opening an issue or asking for help, include:

• install method and nanobot --version;
• operating system and Python version;
• the command you ran;
• relevant nanobot status output;
• sanitized config snippets, especially provider, model, channel, and tool settings;
• gateway logs from nanobot gateway --verbose;
• whether nanobot agent -m "Hello!" works.

Never paste real API keys, bot tokens, OAuth tokens, or private chat IDs into public issues.

If you find a docs mistake, outdated command, or confusing step, please open an issue: https://github.com/HKUDS/nanobot/issues.