Wardenby Bitmill
Documentation

Troubleshooting

This page covers the most common issues you may encounter when running Warden, along with their causes and fixes.

Daemon Not Picking Up Changes

Symptom: You edited a rule file or updated Warden’s configuration, but the behavior has not changed.

Cause: The daemon caches configuration at startup. File changes are detected via filesystem polling (every 5 seconds on most platforms), but certain changes require an explicit reload.

Fix:

warden daemon restart

If the issue persists, verify the configuration file is valid:

warden rules list

If the output shows your changes, the daemon has reloaded successfully. If not, check file permissions and ensure the configuration file is in the expected location.

Binary Version Mismatch

Symptom: Warden logs warnings like version mismatch: daemon v58, hook binary v57 or hooks behave inconsistently.

Cause: The Warden daemon and hook binary are separate executables. If you updated one but not the other (or if a package manager updated the binary but the daemon is still running the old version), they will disagree on protocol versions, signal types, and state formats.

Fix:

warden daemon stop
warden update --yes
warden daemon start

Always restart the daemon after updating the binary. The warden update command will remind you to do this, but manual installations may skip the reminder.

Rules Not Loading

Symptom: Custom rules you defined in .warden/rules/ are not being applied.

Cause: Several possible issues:

  1. Wrong file extension — rule files must end in .toml. Other extensions are ignored.
  2. Syntax error — a malformed TOML file is skipped entirely rather than partially loaded. Warden logs a parse error but does not surface it to the assistant.
  3. Wrong directory — project rules go in .warden/rules/ at the project root. User rules go in ~/.warden/rules/. Placing a file in the wrong location means it applies to the wrong scope.
  4. Rule precedence — a higher-priority rule may be overriding your custom rule. Use warden rules list --verbose to see the full precedence chain.

Fix: Check the daemon log for parse errors:

warden daemon logs | grep -i "rule"

Validate your TOML syntax with any TOML validator. Verify the file is in the correct directory.

CI Environment Issues

Symptom: Warden does not function in CI/CD pipelines, or hooks time out.

Cause: CI environments often lack the prerequisites Warden expects:

  1. No daemon — Warden’s daemon must be explicitly started in CI. It does not auto-start.
  2. No persistent state — CI containers are ephemeral. Session state from previous runs is unavailable unless the .warden/ directory is cached.
  3. Process detection fails — Warden detects the assistant by scanning the process list. In CI, the assistant may run under a different process name or be invoked through a wrapper script.

Fix:

# In your CI setup step:
warden daemon start --ci

The --ci flag adjusts behavior for non-interactive environments: it disables process-based assistant detection (falls back to environment variable WARDEN_ASSISTANT), skips idle-session analysis (Dream worker does not start), and sets a higher hook timeout (200ms instead of 50ms) to account for slower CI hardware.

Hooks Not Firing

Symptom: Warden is running but tool calls are not being intercepted.

Cause:

  1. Hook registration failed — the assistant’s hook configuration does not point to Warden’s hook script.
  2. Wrong hook type — Warden registers for PreToolUse and PostToolUse events. If the assistant only supports a subset, some hooks will not fire.
  3. Assistant not detected — Warden could not identify the running assistant and defaulted to passthrough mode.

Fix: Verify hook registration:

warden status

The status output includes a hooks section showing which hooks are registered and their current state. If hooks show as not registered, run:

warden hooks install

This writes the necessary hook configuration to the assistant’s settings file.

MCP Not Responding

Symptom: The assistant cannot call Warden’s MCP tools, or MCP tool calls return errors.

Cause:

  1. MCP server not started — the MCP server is part of the daemon. If the daemon is not running, MCP tools are unavailable.
  2. Transport mismatch — the assistant is configured for stdio transport but the daemon is listening on a socket (or vice versa).
  3. Port conflict — if using socket transport, another process may be using the configured port.

Fix: Check MCP server status:

warden status --mcp

This shows the MCP server’s transport type, listen address, and connection count. If the server is not running, restart the daemon. If there is a transport mismatch, update the assistant’s MCP configuration to match.

High Latency

Symptom: Tool calls take noticeably longer when Warden is running.

Cause: Warden’s hook processing should complete in under 50ms. If it is taking longer:

  1. Antivirus interference — some antivirus software scans every process spawn. Since hooks invoke the Warden binary as a subprocess, each tool call triggers an AV scan.
  2. Disk I/O contention — session state is read from and written to disk on every hook call. If the disk is under heavy load, this adds latency.
  3. Large session state — sessions with very high turn counts (1000+) accumulate large state files that take longer to deserialize.

Fix:

  • Exclude the Warden binary directory from antivirus real-time scanning
  • Use an SSD for the .warden/ directory (or set WARDEN_STATE_DIR to a fast location)
  • For long sessions, run warden session compact to trim accumulated state

Stale Session State

Symptom: Warden’s status shows a session that ended hours ago, or trust/phase values seem wrong for the current activity.

Cause: Sessions are identified by the assistant’s process ID. If the assistant crashes without a clean exit, Warden does not receive a session-end signal and the old session lingers.

Fix:

warden session end --force

This terminates the current session regardless of process state and starts fresh. The old session’s data is preserved in .warden/sessions/archive/ for Dream analysis.

If stale sessions are a recurring problem, enable the watchdog:

warden daemon config set watchdog.enabled true

The watchdog periodically checks whether session owner processes are still alive and auto-ends orphaned sessions.