Your lightweight open-source personal agent.
Troubleshooting
Use the first check that matches what you see, then follow its next step. This avoids investigating the browser or a chat app before confirming nanobot can start and contact its model.
Fast Diagnosis Order
- The
nanobotcommand is not found, or nanobot will not start: check Installation Problems. Runnanobot --versionto confirm the command is available. - nanobot starts, but does not answer: run
nanobot status. Check that it points to the config and workspace you expect and that the active model is ready. This command does not contact the model; if setup is incomplete, follow its WebUI Settings → Models or CLI wizard instructions. - Status looks ready, but a test question fails: run
nanobot agent -m "Hello!". If it fails, troubleshoot Provider and Model Problems before testing the gateway or a chat app. - The test question works, but the browser or chat app does not: start
nanobot gatewayand follow Gateway Problems, WebUI Problems, or Chat App Problems, depending on what is failing.
nanobot status checks local configuration and provider readiness without making a model request. A successful nanobot agent -m "Hello!" confirms the local agent can get a reply; it does not prove that a gateway, browser, or chat app is working.
Empty topics after a WebUI restart
The Restart button in WebUI settings does not create a conversation or add messages to an existing conversation. Reopening WebUI or reconnecting to the gateway also does not save a topic until a message or another session action creates it.
Older gateway versions could save an empty topic when the Restart button had no current chat. Update the gateway to stop creating these topics. Existing topics are not deleted by the update; check their contents before removing them. A typed /restart command remains part of that chat's display history.
If settings stay disabled after a restart while another tab has reconnected, reload the affected page. Updated WebUI clients track restart completion per tab, so one tab cannot leave another tab waiting by clearing the shared restart marker.
Session storage overlaps the workspace
Sessions live at <config-dir>/sessions/<workspace-id>/, outside the agent workspace. If startup reports a conflict, compare the printed paths. A valid layout is bot/config.json, bot/sessions/, and bot/workspace/.
--workspace overrides agents.defaults.workspace without moving sessions. The override is temporary for agent and gateway; webui --workspace saves it to the config.
To fix an existing instance:
- Stop the instance and back up its config directory and workspace.
- Keep the workspace and
.nanobot/workspace-idin place. Move the config file and its runtime data, including sessions, to a directory outside the workspace. - Update
--configin your launch command or service, check relative paths, and restart.
Moving only the config leaves history behind. Choosing a new workspace without moving its contents (including memory, skills, and .nanobot/workspace-id) can start an empty workspace with a different session identity.
How to Read nanobot status
nanobot status does not call a model. It checks the selected config and workspace, resolves environment references, and validates the local settings required by the active provider/model without constructing a provider client.
The output has this shape:
nanobot Status
Config: /path/to/config.json ✓
Workspace: /path/to/workspace ✓
Model: provider/model-name (preset: primary)
Agent: ✓ provider/model configuration is ready
Provider A: not set
Provider B: ✓
Local Provider: ✓ http://localhost:11434/v1
OAuth Provider: ✓ (OAuth)
Read it like this:
| Line | Good sign | What to do if it looks wrong |
|---|---|---|
Config |
It points to the config file you meant to use and shows ✓. |
Run nanobot onboard, or pass --config to nanobot agent, gateway, or serve when testing a non-default instance. |
Workspace |
It points to the workspace you meant to use and shows ✓. |
Run nanobot onboard, create the folder, fix permissions, or pass --workspace on commands that support it. |
Model |
It shows the active model or the preset name you expect. | Set agents.defaults.modelPreset to the intended preset, or check /model if you changed models during a chat session. |
Agent |
It says provider/model configuration is ready. |
Follow the printed WebUI or CLI setup route, then run nanobot status again. |
| Provider rows | The provider used by the active preset shows ✓, an OAuth marker, or a local URL. |
Configure only the active provider first. It is normal for unused providers to say not set. |
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.
| Symptom | Check |
|---|---|
python: command not found |
Try python3 --version on macOS/Linux or py --version on Windows. Then replace python in docs commands with the command that worked. |
curl: command not found |
The macOS/Linux one-command installer could not download the script. Install curl, or use a manual isolated install such as uv tool install nanobot-ai or pipx install nanobot-ai. |
irm is not recognized |
PowerShell could not run the download helper. Use manual install: uv tool install nanobot-ai, pipx install nanobot-ai, or py -m pip install nanobot-ai inside an environment you control. |
Could not download raw.githubusercontent.com |
Your network, proxy, or firewall blocked the installer script download. Use manual install from PyPI, or configure your proxy and rerun the command. |
nanobot: command not found |
With the recommended installer, reuse its printed full command; with uv/pipx, use uv tool run --from nanobot-ai nanobot ... / pipx run --spec nanobot-ai nanobot .... For a pip install, use <installing-python> -m nanobot ... from that same environment. A system python or py may not contain the isolated installation. |
No module named nanobot |
You are running a different Python than the one used for installation. Run python -m pip show nanobot-ai, python3 -m pip show nanobot-ai, or py -m pip show nanobot-ai, matching the command that installed nanobot. |
pip is not available |
When the installer uses a virtual environment, it tries python -m ensurepip --upgrade. If that fails, install pip for that Python, or use a Python installer/distribution that includes pip. |
externally-managed-environment |
Your system Python blocks global pip installs. Use the one-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or create a virtual environment; do not add --break-system-packages for nanobot. |
| Installer chose the wrong Python | Set PYTHON before running the installer, such as `curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh |
| Editable source install does not update | From the repo root, run python -m pip install -e . again with the Python command used for development, then check python -m nanobot --version or nanobot --version. |
| WebUI build tools missing | They are only needed for WebUI development. Packaged installs already include the WebUI bundle. |
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:
| Symptom | Check |
|---|---|
| JSON parse error | Validate commas, braces, and quotes. Most docs examples are partial snippets to merge. |
| Unknown or missing provider | Use provider registry names such as openrouter, anthropic, openai, ollama, vllm, lm_studio, or define a custom OpenAI-compatible provider key under providers and reference that exact key from the active preset. |
| snake_case vs camelCase confusion | Both are accepted, but docs use camelCase because nanobot writes config with aliases such as apiKey, modelPresets, intervalS. |
| Environment variable error | ${VAR_NAME} references are resolved at startup. Set the variable before running nanobot. |
| Edited config but behavior did not change | Restart nanobot gateway; long-running processes read config at startup. |
After editing config, check the shortest path to an Agent reply:
nanobot status
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.
| Symptom | Likely cause |
|---|---|
| 401, unauthorized, invalid API key | Key is missing, expired, pasted with whitespace, or under the wrong provider key. |
| Model not found | The model ID belongs to a different provider or gateway. |
| Provider cannot be inferred | Pin modelPresets.<name>.provider in the active preset instead of using "auto". For legacy direct configs, pin agents.defaults.provider. |
| Local model connection refused | Ollama, vLLM, LM Studio, or another local server is not running, or apiBase points to the wrong port. |
| Bedrock validation error | Check AWS region, credentials, model access, model ID, and whether the model supports Converse. |
| OAuth provider fails | Run the matching login command: openai-codex, xai-grok, or github-copilot, normally with --set-main. |
| Codex OAuth needs a proxy | Set the address in Settings → Advanced → Shared proxy and enable Use proxy for OpenAI Codex before login. In config.json, use network.proxy and providers.openaiCodex.useProxy: true. This applies to login, token refresh, and Codex API requests. |
| Codex login runs on a remote/headless machine | In the WebUI, open ChatGPT in your local browser; when the localhost callback page cannot load, copy the full http://localhost:1455/auth/callback?... URL from the address bar and paste it into the WebUI dialog. From the CLI, open the printed URL locally and paste the same callback URL back into the terminal. |
| Codex login runs in Docker | Start the container with docker run -it so the OAuth flow has an interactive terminal. |
| Codex says a model is not supported with a ChatGPT account | Use provider openai_codex with a Codex model such as openai-codex/gpt-5.6-sol. Do not use the direct-API openai/... prefix with Codex OAuth. |
Config says providers.openai_codex conflicts with the built-in provider |
Under providers, keep only the canonical openaiCodex settings key and remove a duplicate openai_codex key. A model preset's provider value remains openai_codex. |
| xAI OAuth needs a proxy | Set network.proxy and providers.xaiGrok.useProxy: true before login, or use the shared address and provider switch in Settings. This applies to OAuth discovery, token exchange/refresh, and Grok subscription requests. |
| xAI login runs on a remote/headless machine | In the WebUI, finish sign-in in your local browser; if the loopback redirect cannot reach the server, copy the final URL from the address bar into the WebUI dialog. From the CLI, run nanobot provider login xai-grok interactively, open the printed URL elsewhere, and paste the final callback URL or authorization code when prompted. |
| xAI returns 403 or subscription access denied | Confirm the signed-in account has an eligible X Premium / Grok subscription, then run nanobot provider login xai-grok again. This provider does not use an xAI API key or X Developer OAuth. |
xAI returns 400 invalid-argument |
Read the bounded Response body appended to the provider error. Hosted x_search is sent only when xAI's model catalog advertises supportsBackendSearch; the model ID grok-4.5 itself is valid. |
| xAI model or X Search stops working after an upstream release | The integration follows Grok Build's public OAuth/proxy client contract. Update nanobot if xAI changes that contract. |
Codex certificate verification errors
Codex model requests fail if the server certificate is untrusted, expired, or does not match the hostname. nanobot does not retry these requests with certificate verification disabled. This also applies when WebSocket falls back to HTTP.
Check the gateway machine's clock and the certificate chain used by your network or proxy. If your organization requires a private CA, obtain its trusted PEM bundle from your administrator and set SSL_CERT_FILE in the gateway process environment before restarting. SSL_CERT_DIR is also supported for an OpenSSL-compatible certificate directory. For model requests, these CA settings work with or without the explicit Codex proxy; they do not change the selected proxy route. Never trust a certificate supplied by an unknown error page or disable certificate verification.
These model-request CA settings do not change OAuth login or model-catalog transport configuration. If those operations fail through a TLS-inspecting proxy, use an administrator-approved route that preserves the service's trusted certificate chain. Repeated sign-in does not repair a certificate error. Existing chats and credentials are not deleted by this failure.
Local Token Estimation
Gateway loads the fallback tokenizer in the background, caching it beside the active config under cache/tiktoken unless TIKTOKEN_CACHE_DIR or DATA_GYM_CACHE_DIR is set; chats use UTF-8 byte estimates while loading or after failure (restart to retry), and token estimates may differ from model usage.
Langfuse Problems
Langfuse tracing is optional and controlled by environment variables.
| Symptom | Check |
|---|---|
LANGFUSE_SECRET_KEY is set but langfuse is not installed |
Install langfuse in the same Python environment that runs nanobot, then restart the process. |
| No traces appear | Set LANGFUSE_SECRET_KEY, LANGFUSE_PUBLIC_KEY, and LANGFUSE_BASE_URL before starting nanobot. |
| Wrong Langfuse project or region | Check that the key pair and LANGFUSE_BASE_URL come from the same Langfuse project/region. |
| Only some providers trace | Langfuse tracing applies to OpenAI-compatible provider calls and the Codex OAuth provider; other native providers may not use either client path. |
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:
| Surface | Default |
|---|---|
| Gateway health endpoint | http://127.0.0.1:18790/health |
| WebUI/WebSocket channel | http://127.0.0.1:8765 |
OpenAI-compatible API (nanobot serve) |
http://127.0.0.1:8900 |
Common gateway checks:
nanobot gateway --verbose
| Symptom | Check |
|---|---|
| Port already in use | Change gateway.port, channels.websocket.port, or the --port CLI flag for the relevant command. |
WebUI opened on 18790 but shows nothing useful |
Open 8765; 18790 is the health endpoint. |
| Config changes ignored | Restart the gateway. |
Startup pauses at Installing optional feature |
An enabled channel is missing its Python dependencies. See Slow Optional Channel Dependency Installation. |
| Heartbeat never runs | Keep the gateway running, add tasks under <workspace>/HEARTBEAT.md -> ## Active Tasks, and make sure gateway.heartbeat.enabled is true. |
| Cron jobs disappeared after switching workspaces | Cron jobs are workspace-scoped at <workspace>/cron/jobs.json; check you are using the intended workspace. |
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
Run nanobot webui to prepare the local WebSocket channel and open the browser. Finish model setup in Settings → Models.
Manual WebSocket configuration
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
For first access, copy the complete login link printed by nanobot webui, including the fragment after #. In WSL, open that link in your Windows browser if automatic opening fails. The plain page address does not sign in a new browser.
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.
| Symptom | Check |
|---|---|
| A temporary chat disappeared after a reload or reconnect | This is expected. Temporary chats exist only for the current WebUI connection and are not saved to history or memory. Use a regular topic for anything you need to retain. |
A skills.sh install says that npx is required |
Install Node.js with npx on the gateway machine, or choose a SkillHub skill that does not require npx. |
| A remote browser says skill installation is disabled | Install from a same-machine WebUI. For a private deployment where every authenticated user is trusted to install third-party skill instructions or scripts, explicitly enable tools.webuiAllowRemotePackageInstall. |
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:
| Symptom | Check |
|---|---|
| Bot never replies | Gateway is not running, the channel is not enabled, or the bot/app token is wrong. |
| Unknown sender ignored | Configure allowFrom, pairing, or the channel-specific allow list. |
| Telegram shows a saved configuration but cannot complete a live check | The token is saved. Confirm the gateway can reach api.telegram.org, or open Channels → Telegram → Advanced → Network proxy and enter an HTTP or SOCKS proxy. |
| Telegram rejects the token | Copy the current token from BotFather or regenerate it. |
| Telegram receives no messages | Confirm the channel is enabled, the gateway is running, and the sender is paired or listed in allowFrom. |
| Discord replies missing | Enable Message Content intent and invite the bot with the required permissions. |
| WhatsApp or WeChat login expired | Re-run nanobot channels login whatsapp or nanobot channels login weixin. |
| Chat app works but WebUI does not | The provider and gateway are likely fine; debug the WebSocket channel separately. |
See chat-apps.md for channel-specific setup.
Tool and Workspace Problems
| Symptom | Check |
|---|---|
| File access denied | Check tools.restrictToWorkspace and whether the target path is inside the active workspace. |
| Shell commands fail in Docker | Sandbox settings may need Linux capabilities; see deployment.md. |
| Web fetch blocked | SSRF protection blocks unsafe targets; use tools.ssrfWhitelist only for trusted private networks. |
| MCP tools missing | Check tools.mcpServers, server startup command, environment variables, and tool allow list. |
| Generated artifacts are missing | Check the active workspace and channel media directory. |
Memory and Session Problems
| Symptom | Check |
|---|---|
| Conversation context seems wrong | Confirm the active workspace and session. WebUI chats and chat app threads may use different sessions. |
| Memory does not update immediately | Dream consolidation is periodic; recent turns still live in session history. |
Sessions disappear after changing --config |
Sessions follow the config directory at <config-dir>/sessions/<workspace-id>/; use the original config path or copy that sessions/ directory into the new config directory while nanobot is stopped. |
| Sessions disappear after moving a workspace | Keep the workspace's .nanobot/workspace-id file with the move or backup. If it was lost, restore that marker from backup before starting nanobot. |
| You want one shared session across devices | Set agents.defaults.unifiedSession intentionally; otherwise keep separate sessions. |
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 statusoutput; - 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.