zeroclaw/docs/troubleshooting.md

ZeroClaw Troubleshooting

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

Last verified: February 20, 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 fails on low-RAM / low-disk hosts

Symptoms:

• cargo build --release is killed (signal: 9, OOM killer, or cannot allocate memory)
• Build crashes after adding swap because disk space runs out

Why this happens:

• Runtime memory (<5MB for common operations) is not the same as compile-time memory.
• Full source build can require 2 GB RAM + swap and 6+ GB free disk.
• Enabling swap on a tiny disk can avoid RAM OOM but still fail due to disk exhaustion.

Preferred path for constrained machines:

./bootstrap.sh --prefer-prebuilt

Binary-only mode (no source fallback):

./bootstrap.sh --prebuilt-only

If you must compile from source on constrained hosts:

1. Add swap only if you also have enough free disk for both swap + build output.
2. Limit cargo parallelism:

CARGO_BUILD_JOBS=1 cargo build --release --locked

1. Reduce heavy features when Matrix is not required:

cargo build --release --locked --no-default-features --features hardware

1. Cross-compile on a stronger machine and copy the binary to the target host.

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

• operations-runbook.md
• one-click-bootstrap.md
• channels-reference.md
• network-deployment.md