harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
zeroclaw/docs/troubleshooting.md

2.6 KiB
Raw Blame History

ZeroClaw Troubleshooting

This guide focuses on common setup/runtime failures and fast resolution paths.

Last verified: February 18, 2026.

Installation / Bootstrap

cargo not found

Symptom:

  • bootstrap exits with cargo is not installed

Fix:

./bootstrap.sh --install-rust

Or install from https://rustup.rs/.

Missing system build dependencies

Symptom:

  • build fails due to compiler or pkg-config issues

Fix:

./bootstrap.sh --install-system-deps

zeroclaw command not found after install

Symptom:

  • install succeeds but shell cannot find zeroclaw

Fix:

export PATH="$HOME/.cargo/bin:$PATH"
which zeroclaw

Persist in your shell profile if needed.

Runtime / Gateway

Gateway unreachable

Checks:

zeroclaw status
zeroclaw doctor

Verify ~/.zeroclaw/config.toml:

  • [gateway].host (default 127.0.0.1)
  • [gateway].port (default 3000)
  • allow_public_bind only when intentionally exposing LAN/public interfaces

Pairing / auth failures on webhook

Checks:

  1. Ensure pairing completed (/pair flow)
  2. Ensure bearer token is current
  3. Re-run diagnostics:
zeroclaw doctor

Channel Issues

Telegram conflict: terminated by other getUpdates request

Cause:

  • multiple pollers using same bot token

Fix:

  • keep only one active runtime for that token
  • stop extra zeroclaw daemon / zeroclaw channel start processes

Channel unhealthy in channel doctor

Checks:

zeroclaw channel doctor

Then verify channel-specific credentials + allowlist fields in config.

Service Mode

Service installed but not running

Checks:

zeroclaw service status

Recovery:

zeroclaw service stop
zeroclaw service start

Linux logs:

journalctl --user -u zeroclaw.service -f

Legacy Installer Compatibility

Both still work:

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install.sh | bash

install.sh is a compatibility entry and forwards/falls back to bootstrap behavior.

Still Stuck?

Collect and include these outputs when filing an issue:

zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor

Also include OS, install method, and sanitized config snippets (no secrets).

Related Docs