> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bead.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud worktree troubleshooting

> Use cloud worktree troubleshooting steps to resolve stale preparation, busy services, file drift, and lost execution replies.

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

```bash theme={null}
bead worktree status
bead worktree --help
```

## Preparation is stale

Run your preparation step after dependencies, schema, or declared preparation inputs change:

```bash theme={null}
bead worktree prepare
```

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:

```bash theme={null}
bead worktree stop
```

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](https://docs.bead.run/worktrees/environment.md).

## 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.

```bash theme={null}
bead worktree status --execution EXECUTION_ID
```

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

```bash theme={null}
bead worktree status --all
```

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

```bash theme={null}
bead worktree down
```

Verify destruction is acknowledged. Prepared snapshots and templates remain separately retained. See [Recover execution and clean up](https://docs.bead.run/worktrees/recovery.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.