Skip to main content
For cloud worktree troubleshooting, run commands at the local Git worktree root. Keep the printed machine and execution identifiers.

​
Preparation is stale

Run your preparation step after dependencies, schema, or declared preparation inputs change:
Source sync does not implicitly install dependencies. Check that your preparation script and required tools exist in the selected Linux template. Laptop tools are not available remotely.

​
The machine is busy

bead worktree dev SERVICE owns the machine while the service runs. Stop it with Ctrl-C, or use:
Then run the next managed command. Dev syncs once at startup. Restart it after local edits to sync the new files.

​
Managed files drifted

Direct same-organization exec or file operations can change worktree-managed files. The next managed sync checks that state. Inspect the reported paths and preserve needed guest changes before reconciling with local authoritative source. Guest-only caches and build outputs can remain across syncs. The remote repository has no local Git history. For version stamping, use BEAD_GIT_COMMIT and BEAD_GIT_BRANCH rather than git log or git describe.

​
An environment value was rejected

Worktree env names reject reserved BEAD_, loader, and shell controls, including PATH, NODE_OPTIONS, BASH_ENV, and ENV. Keep values out of command arguments. Check configured env files and project/service vault scope; see Environment files.

​
An execution reply was lost

Recover the same execution rather than repeating it: status does not wake the machine. If it is paused, run bead resume "$MACHINE_ID" and wait until it is running before recovering output; retrieve it before bead worktree up or another managed command retires the previous spool.
Output remains until the next managed command or machine deletion, with a 64 MiB cap. An artifact-pull failure is separate from the remote command’s exit status.

​
Machine creation has an unknown outcome

Inspect existing authorized resources before another create. After the replay window, bind an identified machine explicitly with bead worktree up --machine MACHINE_ID rather than creating blindly.

​
Finish a branch

Verify destruction is acknowledged. Prepared snapshots and templates remain separately retained. See Recover execution and clean up.