ZeroClaw Troubleshooting: PATH, Config, Provider and Dashboard Errors

Start with the exact error, then test one layer at a time: executable, configuration, model connection, dashboard and messaging channel. This hub gives you the observed message, the next action and a way to check whether it worked.

Version notice: Error examples were reproduced on ZeroClaw v0.8.5, macOS arm64, on 11 October 2026 using isolated configurations and local endpoints. Windows PATH steps and external provider/channel recovery are guidance, not end-to-end tests. Verify your release with zeroclaw --version; messages can change between versions. No live messaging credentials were used.

Find your symptom

Before changing anything

Run these against the same config directory your failing process uses:

zeroclaw --version
zeroclaw status

For a separate test directory, pass --config-dir ./zeroclaw-test on every command. For an existing installation, replace that directory with your actual one. A command that inspects one configuration cannot diagnose a service running another.

Back up config.toml before editing or migrating it. Do not delete your installation directory, memory or workspace as a first troubleshooting step. When sharing a log, redact API keys, bot tokens, pairing codes, bearer tokens, personal messages and private paths.

1. ZeroClaw command not found

Observed in a shell whose PATH excluded the downloaded executable:

zsh:1: command not found: zeroclaw

This is a shell lookup failure: ZeroClaw has not started yet. First locate the binary you installed. From the directory containing it, test the full or relative path:

./zeroclaw --version

On Windows PowerShell, run the executable from its folder:

.\zeroclaw.exe --version
Get-Command zeroclaw -ErrorAction SilentlyContinue

If that works, the binary's directory is missing from PATH in the current session. On macOS or Linux, if you installed it in $HOME/.local/bin, test:

export PATH="$HOME/.local/bin:$PATH"
command -v zeroclaw
zeroclaw --version

Use your real install directory if it differs. For a lasting fix, add the directory to the appropriate shell startup configuration and open a new terminal. On Windows, add the folder containing zeroclaw.exe to your user Path through environment-variable settings, then open a new PowerShell window. Do not add the executable filename itself to Path.

Recovery check: zeroclaw --version works without a path prefix and reports the intended version. If the direct-path command fails too, check the operating-system/CPU release asset and file permissions using the installation guide. Changing PATH will not repair an incompatible binary.

2. Config is malformed or resets to defaults

An isolated config with level = "read_only" produced this error inside the migration JSON:

unknown variant `read_only`, expected one of `readonly`, `supervised`, `full`
in `risk_profiles.reader.level`

The same run warned that the malformed risk_profiles section was reset to defaults for that run, and its values were not in effect. A process that starts after such a warning is not evidence that your intended policy loaded.

Run the strict check:

zeroclaw --config-dir ./zeroclaw-test config migrate --json

For this specific error, edit the existing risk-profile table to use level = "readonly". Preserve your other settings. For other errors, repair the named field or table rather than copying a different section blindly.

After an older configuration is migrated, run the command again. Migration can change the file and create a backup; the second check verifies the resulting current configuration. Do not bypass a degraded-security startup refusal to conceal malformed security settings.

The known-good schema-3 fixture returned:

{
  "error": null,
  "migrated": false,
  "schema_version": 3,
  "valid": true
}

Also check references: an agent's model_provider = "ollama.local" must match [providers.models.ollama.local]; its risk profile must match a configured alias. Use the tested config and migration guide for current examples.

Recovery check: the current config passes the strict check, and restarting your process produces no malformed-section warning. Parser validity does not prove provider connectivity or tool permissions.

3. Provider call failed or model server unavailable

With the Ollama endpoint deliberately set to an unused local port, the agent returned:

Error: The local model server at http://127.0.0.1:1/v1/chat/completions is unavailable. Start it or update the endpoint.

Port 1 was a failure fixture, not a recommended endpoint. For a normal local Ollama setup, the sample provider URI is http://127.0.0.1:11434.

1. Confirm that the chosen agent references the intended provider alias and that the URI points to the server's actual host and port.
2. Start the local server if it is stopped. For Ollama, use ollama serve only if a server is not already running.
3. Run ollama list and confirm the configured model name is present. Download it with ollama pull MODEL_NAME if needed.
4. Try one direct agent turn before testing Telegram or the dashboard:

zeroclaw --config-dir ./zeroclaw-test agent -a assistant -m "Reply with the single word Ready. Do not use tools."

assistant must be an existing agent alias. The minimal local configuration was previously tested with a real model response; this hub's failure test did not run inference.

If ZeroClaw runs inside a container, 127.0.0.1 means that container, not your host machine. Choose a reachable endpoint for that deployment. Check proxy, firewall and TLS settings if the service is reachable elsewhere but not from the runtime host.

For a hosted provider, inspect the underlying status and message rather than treating “provider call failed” as one diagnosis:

These hosted cases are diagnostic guidance; no live hosted API failures were reproduced here. Do not paste credentials into a support ticket or repeatedly retry an invalid key.

Recovery check: the direct agent turn returns model text without a provider error. A successful config check alone is insufficient.

4. Dashboard or gateway errors

Start the gateway in the foreground so you can read its actual listener address:

zeroclaw --config-dir ./zeroclaw-test gateway start

The default v0.8.5 address is http://127.0.0.1:42617/, unless overridden. The tests below used port 40317 to avoid touching an existing service. A loopback address is reachable from that machine; opening it on another device targets that other device instead.

Port already in use

Starting a second gateway on the test port returned:

Error: Port 40317 is already in use, so the gateway could not start.

Check whether your intended gateway is already running. Reuse it if it has the correct configuration, or stop only the duplicate you own. To test another port:

zeroclaw --config-dir ./zeroclaw-test gateway start --port 42618

Recovery check: startup succeeds and you open the address printed by that process. Do not terminate an unidentified process merely to free a port.

HTTP 401: pair first

An unauthenticated request to /api/status on the running test gateway returned HTTP 401:

{"error":"Unauthorized — pair first via POST /pair, then send Authorization: Bearer <token>"}

This means the API listener answered and requires authentication. Open the dashboard on the gateway host and complete its pairing flow using the code from that same instance. If needed, retrieve its code locally:

zeroclaw --config-dir ./zeroclaw-test gateway get-paircode

Keep the code and resulting bearer token private. If a saved browser session stops working after a token/config change, pair again through the dashboard. Disabling pairing or binding publicly is not a repair for a stale session.

Recovery check: an authenticated dashboard session can read status. The 401 test here confirmed the boundary; it did not test authenticated chat.

Missing dashboard assets

The official macOS arm64 archive tested here contained sibling web/dist assets; the gateway served dashboard HTML at /. Preserve those assets when installing. A successful API listener does not always mean the dashboard files are available in your installation.

If startup reports the dashboard unavailable, restore assets from the matching release or point gateway.web_dist_dir / ZEROCLAW_WEB_DIST_DIR to the compiled frontend directory containing index.html. Use the version-matched frontend, not an arbitrary checkout. The tagged gateway can discover packaged assets, so inspect what it actually serves before assuming an explicit missing path makes it API-only.

Recovery check: / returns the dashboard and its scripts load; then complete pairing. See the gateway guide for the broader setup, using this hub's archive observation when checking packaged assets.

5. Channel missing or bot silent

A config with no usable real-time channel returned:

No real-time channels configured. Run `zeroclaw quickstart` to set one up.

A send attempt referencing an absent Telegram instance returned:

Error: Failed to send message via telegram.demo

Caused by:
    [channels.telegram.demo] not configured

These messages indicate missing runtime wiring, not a proven Telegram outage. Inspect the same config your channel process uses:

zeroclaw --config-dir ./zeroclaw-test channel list
zeroclaw --config-dir ./zeroclaw-test channel doctor

For Telegram on v0.8.5, check three separate layers:

• Connection: [channels.telegram.home] is enabled and has a valid bot token stored through the masked configuration prompt.
• Routing: the intended existing agent includes telegram.home in its channels list. Preserve other bindings when editing the list.
• Authorization: matching peer groups authorize the intended user, or the private first-user pairing flow is completed. The old channel-local allowed_users field is not the current schema.

Follow the tagged Telegram setup for secret entry, agent binding and peer groups. Do not use wildcard peer authorization as a shortcut to make a private bot respond.

A healthy channel connection does not prove model connectivity or inbound authorization. If the bot connects but stays silent, inspect routing and peer authorization, then run the direct model test above. If health checks report authentication failures, check the token privately; if they report network failures, check connectivity from the runtime host. Those live-service branches were not reproduced with real credentials here.

Recovery check: channel inventory contains the intended instance, its health check passes, and one authorized test message receives a reply from the intended agent. Creating a bot or completing a real account's authorization may require your interaction; it was not needed to reproduce the missing-channel errors.

Collect a useful support report

Include the ZeroClaw version, OS/CPU, failing command, config directory choice, sanitized error and timestamp, and which checks above passed. Say whether the issue occurs in the direct CLI, gateway or channel. Share only the relevant non-secret config fields. This narrows the failure without exposing credentials or an entire conversation log.

Implementation references: v0.8.5 release, config schema, gateway, and Telegram routing and authorization.