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:15

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

Where: heddle mount or any command that auto-mounts a virtualized workspace. The binary you're running was built without the mount feature flag. Virtualized workspaces are supported across Linux (FUSE), macOS (FSKit), and Windows (ProjFS); the feature just has to be compiled in.

Fix: rebuild with the feature enabled, or use materialized threads (heddle start + a real checkout) instead.

$ cargo build --release --features mount

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

3. No current thread

Where: heddle capture --split invoked outside a thread checkout. The recovery advice reads "Run heddle capture --split from an active thread checkout, or retry with heddle thread switch <name> to choose a thread explicitly." Splitting moves dirty paths into another thread, which only makes sense when you've taken responsibility for a thread.

Fix: start or switch to a thread first, then re-run capture --split, naming the target thread with --into and each prefix with --path.

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

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

4. No dirty paths matched the requested split prefixes

Where: heddle capture --split --path <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 move into the target thread 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 --path prefix that matches one of them.

$ heddle status
$ heddle capture --split --into "task/side" --path <a-prefix-from-status>

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

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:85

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-snapshot --from-file ./hooks/lint.sh
# or
$ cat ./hooks/lint.sh | heddle hook install pre-snapshot --from-stdin

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

7. state '<id>' not found

Where: heddle redact apply with a state spec the resolver couldn't match. The state argument accepts short or full state IDs, marker names, HEAD, @, or HEAD~N. If none of those resolve, you get this error.

Fix: resolve the state spec first via heddle log or heddle show. The hd- change ID printed by log is the everyday form; the parenthesized content hash beside it works as a prefix too.

$ heddle log
$ heddle redact apply hd-qrvnt3yr1vt6 --path src/leaked.rs --reason "rotated"

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

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

Where: heddle redact apply <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 first, copy the exact path you want gone, then redact.

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

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

9. Repository has no HEAD state for review next

Where: heddle review next / review show on a brand-new repo where no capture has landed yet. Review needs a concrete state to compute against and won't infer one. The advice reads "Capture the current worktree with heddle capture -m "...", then retry."

Fix: capture, then review.

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

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

10. A merge is already in progress

Where: starting a second merge while the first one still has unresolved files. Heddle keeps merge state for the repository so the next agent can pick up where you left off, and that record also blocks a competing merge from racing it. The advice points you at heddle status, then heddle continue or heddle resolve --abort.

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

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

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

Next