Troubleshooting
Common first-run failures and fixes.
castellan: command not found
cargo install --path crates/castellan-cli
# or
cargo build -p castellan-cli && export PATH="$PWD/target/debug:$PATH"
Multiplexer socket missing
castellan multiplexer ensure
# or
castellan herd server
Override socket path: export CASTELLAN_SOCKET=~/.config/castellan/castellan.sock
drift-check fails locally
./scripts/drift-guard.sh
cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
Guardrail edits require manifest updates — see governance policies.
castellan run exits immediately with plugin error
castellan plugin list
castellan plugin info gridworld
Confirm --plugin name matches registry entry. Shell plugin requires bounded argv — no shell injection.
Dashboard shows disconnected
- Start multiplexer:
castellan herd server - Attach session:
castellan herd attach - Check
~/.config/castellan/statusline.json— see statusline
--json output not parseable
castellan run --json emits one CastellanEvent per line (NDJSON). Do not mix with pretty-printed episode JSON — episode file is written to .castellan/episodes/ separately.
Docs build fails
cargo install mdbook mdbook-mermaid --locked
./scripts/install-mermaid-assets.sh
mdbook build book