Warden
beta · v2.14.0
beta · v2.14.0
Documentation

Troubleshooting

Installation Issues

cargo: command not found — Install Rust first via rustup.rs. After installing, restart your terminal so cargo is on PATH.

npx hangs or permission error — On Linux/macOS, you may need to run with sudo if your global npm prefix requires elevated permissions. Alternatively, configure npm to use a user-level prefix: npm config set prefix ~/.npm-global.

Windows PATH not updated — If warden isn’t recognized after install, close and reopen your terminal, or run refreshenv if using Chocolatey.

Firewall blocks the download — npx @bitmilldev/warden init fetches the release from GitHub. If your corporate network blocks this, download manually from the releases page.

Hooks Not Firing

Symptom: Warden is installed but tool calls aren’t being intercepted.

Fix: Check hook registration:

warden doctor

If hooks show as not registered, reinstall for your assistant:

warden install claude-code

Version Mismatch

Symptom: Warden logs warnings like version mismatch or hooks behave inconsistently.

Fix: Update Warden:

warden update --yes

The background server automatically restarts when it detects a new binary version.

Server Not Picking Up Changes

Symptom: You edited a rule file or config, but behavior hasn’t changed.

Fix: The server detects rule file changes automatically and restarts. If it doesn’t, stop and restart manually:

warden server-stop

The server will respawn on the next hook call.

High Latency

Symptom: Tool calls take noticeably longer with Warden running.

Possible causes:

  1. Antivirus interference — some AV software scans every process spawn. Exclude the Warden directory from real-time scanning.
  2. Slow disk — the Warden data directory should be on an SSD.
  3. Very long sessions — sessions with 1000+ turns accumulate state. Starting a new session resolves this.

CI Environment

Symptom: Warden doesn’t function in CI, or hooks time out.

Fix: Set the WARDEN_NO_DAEMON=1 environment variable in CI to skip the background server and run hooks directly. This is slightly slower but avoids process management issues in ephemeral CI environments.