Warden
beta · v4.12.0
beta · v4.12.0
Documentation

Troubleshooting

Installation Issues

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 --debug doctor

If hooks show as not registered, re-run setup — init rewrites the hook configuration for whichever host it detects:

warden init

Version Mismatch

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

Fix: Update Warden:

warden --update --yes

The next hook call compares the running server’s version against the binary and respawns the server if they differ.

Server Not Picking Up Changes

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

Fix: The next hook call compares the running server’s rules.toml against the one on disk and respawns the server if they differ. If that doesn’t happen, stop it manually:

warden --debug 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.