HEDDLE

Reference

Troubleshooting

When you see error X, here's what triggered it and how to fix it. Every error string on this page is grounded against a real source location — if the binary says something word-for-word different, that's the bug, please file it.

1. repository not found at <path>

Where: any command that opens a repository (capture, log, show, status). The CLI walked up from the current directory looking for a .heddle/ directory and didn't find one.

Fix: run heddle init at the repo root, or cd into a directory inside an existing Heddle repo.

$ cd path/to/project
$ heddle init

Source: crates/objects/src/error.rs:14

2. Virtualized workspace requires Linux + heddle built with --features mount

Where: heddle mount or any command that auto-mounts a virtualized workspace. The binary you're running was either built on a non-Linux host, or built without the mount feature flag.

Fix: on Linux, rebuild with the feature enabled; on macOS the FSKit shell is scaffolded but kernel registration is stubbed, so use materialized threads (heddle start + a real checkout) instead.

$ cargo build --release --features mount

Source: crates/cli/src/cli/commands/mount_lifecycle.rs:52

3. No current thread; `heddle capture --split` requires an active thread checkout

Where: heddle capture --split invoked outside an agent checkout. Splitting partitions dirty paths into multiple captures, which only makes sense when you've taken responsibility for a thread.

Fix: start or attach to a thread first, then re-run capture --split.

$ heddle start "task/biscuit-authz"
$ heddle capture --split src/auth --split tests/auth

Source: crates/cli/src/cli/commands/thread_shaping.rs:58

4. No dirty paths matched the requested split prefixes

Where: heddle capture --split <prefix> when the worktree is dirty under some other path. Splitting only operates on paths that actually have pending changes; a prefix that no dirty file lives under produces nothing to capture and is treated as a user error rather than a silent no-op.

Fix: run heddle status to see which paths are dirty, then re-run with a prefix that matches one of them.

$ heddle status
$ heddle capture --split <a-prefix-from-status>

Source: crates/cli/src/cli/commands/thread_shaping.rs:64

5. no captured state found after checkpoint

Where: heddle checkpoint on a repo that has never taken a capture. Checkpointing names a state as worth coming back to — there's nothing to name until at least one capture has run.

Fix: capture first, then checkpoint.

$ heddle capture -m "initial"
$ heddle checkpoint pre-refactor

Source: crates/cli/src/cli/commands/checkpoint.rs:44

6. hook install requires --from-file <path> or stdin input

Where: heddle hook install called interactively with neither --from-file nor a piped script. The companion error hook install received empty stdin; pass --from-file <path> or pipe script content fires when stdin is open but empty.

Fix: pass the script as a file, or pipe its contents.

$ heddle hook install pre-capture --from-file ./hooks/lint.sh
# or
$ cat ./hooks/lint.sh | heddle hook install pre-capture

Source: crates/cli/src/cli/commands/hook.rs:115

7. state '<id>' not found

Where: heddle redact with a state spec the resolver couldn't match. Same failure mode shows up on heddle fork (State not found: <id>, crates/cli/src/cli/commands/fork.rs:39).

Fix: resolve the state spec first via heddle log or heddle show. The 4-char short ID is the everyday form; the full BLAKE3 hash is accepted too.

$ heddle log --short
$ heddle redact hd-d01a --path src/leaked.rs --reason "rotated"

Source: crates/cli/src/cli/commands/redact.rs:398

8. path '<p>' not in state <id>

Where: heddle redact <state> --path <p> when the path doesn't exist in that state's tree. The redactor refuses to write a redaction marker for a file that was never there — that would create a tombstone pointing at nothing.

Fix: inspect the state's tree first, copy the exact path you want gone, then redact.

$ heddle show --tree hd-d01a
$ heddle redact hd-d01a --path crates/cli/secrets.toml --reason "rotated"

Source: crates/cli/src/cli/commands/redact.rs:411

9. repository has no HEAD; capture a state first

Where: heddle review next / review show on a brand-new repo where no capture has landed yet. Review needs a state to compute against.

Fix: capture, then review.

$ heddle capture -m "initial"
$ heddle review next

Source: crates/cli/src/cli/commands/review.rs:318

10. A merge is already in progress. Resolve conflicts or use 'heddle resolve --abort'.

Where: starting a second merge while the first one still has unresolved files. Heddle keeps a MERGE_STATE record under .heddle/ so the next agent can pick up where you left off — that record also blocks a competing merge from racing it.

Fix: either finish the current merge (heddle resolve <path> for each conflict, then heddle capture to land it), or abort.

$ heddle status        # see which files are unresolved
$ heddle resolve src/auth/session.rs --ours
$ heddle capture -m "resolve merge"
# or, to back out:
$ heddle resolve --abort

Source: crates/cli/src/cli/commands/merge/mod.rs:234

Next