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

3.8 KiB
Raw Blame History

ZeroClaw Troubleshooting

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

Last verified: February 19, 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

Build is very slow or appears stuck

Symptoms:

  • cargo check / cargo build appears stuck at Checking zeroclaw for a long time
  • repeated Blocking waiting for file lock on package cache or build directory

Why this happens in ZeroClaw:

  • Matrix E2EE stack (matrix-sdk, ruma, vodozemac) is large and expensive to type-check.
  • TLS + crypto native build scripts (aws-lc-sys, ring) add noticeable compile time.
  • rusqlite with bundled SQLite compiles C code locally.
  • Running multiple cargo jobs/worktrees in parallel causes lock contention.

Fast checks:

cargo check --timings
cargo tree -d

The timing report is written to target/cargo-timings/cargo-timing.html.

Faster local iteration (when Matrix channel is not needed):

cargo check --no-default-features --features hardware

This skips channel-matrix and can significantly reduce compile time.

To build with Matrix support explicitly enabled:

cargo check --no-default-features --features hardware,channel-matrix

Lock-contention mitigation:

pgrep -af "cargo (check|build|test)|cargo check|cargo build|cargo test"

Stop unrelated cargo jobs before running your own build.

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