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 selected config, selected 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 unless you pass explicit paths. Use the same --config and --workspace across status checks and runtime commands when debugging multiple instances:

nanobot status --config ./bot-a/config.json --workspace ./bot-a/workspace
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 --refresh

For an interactive choice between resetting and refreshing, run nanobot onboard and 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

Slow Optional Channel Dependency Installation

Before loading enabled channels, the gateway checks the dependencies declared by their channel manifests. The CLI and WebUI normally install these dependencies when a channel is enabled. Installation during startup is a recovery path for an enabled config whose Python environment no longer has the required packages, for example after manually editing the config, upgrading nanobot, or recreating an isolated uv tool/pipx environment. The gateway waits for the install so an enabled channel is not silently skipped; later starts skip the installation once the dependencies are present.

If access to PyPI is slow in your region, configure pip to use a trusted package index. The installer honors the standard PIP_INDEX_URL environment variable, including when nanobot itself was installed with uv tool:

PIP_INDEX_URL=https://your-trusted-mirror.example/simple nanobot gateway

For the systemd user service created by nanobot gateway install-service, add a drop-in:

systemctl --user edit nanobot-gateway.service

[Service]
Environment="PIP_INDEX_URL=https://your-trusted-mirror.example/simple"

Then reload and restart the service:

systemctl --user daemon-reload
systemctl --user restart nanobot-gateway.service

For a system-level or custom service, use sudo systemctl edit <unit> instead. Prefer an HTTPS index operated by an organization you trust, and do not put index credentials in commands or logs.

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.