Troubleshooting
Common first-run failures and fixes.
flock: command not found
cargo install --path crates/flock-cli
# or
cargo build -p flock-cli && export PATH="$PWD/target/debug:$PATH"
Multiplexer socket missing
flock multiplexer ensure
# or
flock herd server
Override socket path: export FLOCK_SOCKET=~/.config/flock/flock.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.
flock run exits immediately with plugin error
flock plugin list
flock plugin info gridworld
Confirm --plugin name matches registry entry. Shell plugin requires bounded argv — no shell injection.
Dashboard shows disconnected
- Start multiplexer:
flock herd server - Attach session:
flock herd attach - Check
~/.config/flock/statusline.json— see statusline
--json output not parseable
flock run --json emits one FlockEvent per line (NDJSON). Do not mix with pretty-printed episode JSON — episode file is written to .flock/episodes/ separately.
Docs build fails
cargo install mdbook mdbook-mermaid --locked
./scripts/install-mermaid-assets.sh
mdbook build book