# Troubleshoot with dynocap doctor

How to use dynocap doctor to find what is blocking sandboxes, and dynocap doctor --fix to repair it.

HTML: https://dynocap.dev/docs/how-to/troubleshoot-with-doctor

`dynocap doctor` checks everything a sandbox needs and tells you, for each problem, what is wrong and what to run. `dynocap doctor --fix` repairs the problems it can.

```sh
dynocap doctor                  # report only; changes nothing
dynocap doctor --fix            # repair, then report again
dynocap doctor --fix ./project  # check and prepare the runtime ./project uses
```

The runtime doctor checks is the one your project uses: `package.json` means `node:24`; `pyproject.toml`, `uv.lock`, `requirements.txt`, `setup.py`, or `Pipfile` means `python:3.14`; `go.mod` means `go:1.27`. `clone` picks the same way. Pass `--runtime NAME:VERSION` to choose another. With no project (for example, in the dynocap checkout), doctor requires no runtime and lists the prepared ones.

`--fix` builds from the dynocap checkout, which it finds from the `dynocap` binary, so you can run it in any directory.

---

## Reading the Report

```text
Home: /Users/you/.dynocap

OK      platform           macOS 13+; guest architecture aarch64
OK      signing            CLI signature validates and includes the virtualization entitlement.
ERROR   images             The guest image for aarch64 does not match its manifest.
                           Next: Run dynocap doctor --fix to build the guest image (downloads pinned Alpine files; needs Go).
ERROR   daemon             The running daemon started before this dynocap binary was rebuilt, so it runs the old build.
                           Next: Run dynocap doctor --fix to restart the daemon with this dynocap build.

2 required checks failed. Run dynocap doctor --fix to repair them.
```

- `OK` passed; a stopped daemon or a home that does not exist yet is normal. `WARNING` is worth knowing but does not block sandboxes, such as having no runtime prepared outside a project. `ERROR` blocks sandboxes, and the command exits 1.
- `Next:` is the one thing to do. When it names `dynocap doctor --fix`, the command already includes any `--home` or `--runtime` you passed, so you can paste it as printed.
- The last line says whether `--fix` can repair everything, some of it, or nothing.

For scripts, `dynocap doctor --json` prints the same report. Each check has a `fix` field naming its automatic repair. See [JSON Schemas](../reference/cli/json-schemas.mdx).

---

## What `--fix` Repairs

| Check     | Repair                                                                                             | Needs                               |
| :-------- | :------------------------------------------------------------------------------------------------- | :---------------------------------- |
| `daemon`  | Stops a broken daemon, or one from an older build, and starts one from this binary.                | No running sandboxes                |
| `images`  | Builds the guest kernel and initrd. Mismatched files are moved to `replaced-<time>/`, not deleted. | Checkout, Go, network               |
| `runtime` | Prepares and verifies the runtime in an offline guest, like `dynocap runtime prepare`.             | Checkout, Go, network, a signed CLI |

Repairs run in that order, and progress goes to stderr. Each repair prints a build log path, so a failure shows what to read. `--fix` then runs every check again and reports the result.

`--fix` never:

- restarts a daemon that has running sandboxes. Instead it names them, so you can `finish` or `rm` them first;
- deletes image files. It moves them aside;
- re-signs the CLI or rebuilds companions. Reinstall with `brew reinstall baires/tap/dynocap` or `scripts/install.sh`. From a source checkout, run `./scripts/build-macos.sh`.

---

## Checks That Need You

| Check                                    | Cause                                                          | What to do                                                                                           |
| :--------------------------------------- | :------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| `platform`, `backend`                    | Not a Mac with Virtualization.framework, or macOS < 13.        | Use a supported Mac.                                                                                 |
| `signing`                                | The CLI is unsigned or missing the virtualization entitlement. | Reinstall with Homebrew or curl. From a source checkout, run `./scripts/build-macos.sh`.             |
| `dynocap-workspace`, `dynocap-mkruntime` | Companions missing beside the `dynocap` binary.                | Reinstall so both companions stay beside the CLI. A source checkout uses `./scripts/build-macos.sh`. |
| `home`                                   | Home not writable, or `daemon.sock` would exceed 104 bytes.    | Use a shorter writable `--home` or `DYNOCAP_HOME`.                                                   |

---

## Common Situations

### I rebuilt dynocap and now commands fail

The daemon keeps running the old build until it is restarted. `doctor` reports this as an `ERROR daemon`. Run:

```sh
dynocap doctor --fix
```

### `--fix` says Go is missing

The guest agent is compiled during image and runtime builds. Install Go 1.22 or newer (`brew install go`), then run `dynocap doctor --fix` again.

### `--fix` cannot find the source checkout

`--fix` looks beside the `dynocap` binary and above the current directory. A Homebrew or curl install keeps `Package.swift` and `guest/` next to `bin/`, and the CLI resolves its own symlink to that prefix. If you copied the binary by itself, run doctor from a source checkout with the project path: `dynocap doctor --fix ~/code/my-app`.

### `clone` picked the wrong runtime

`clone` prints the runtime it chose and the file it chose by, such as `Using runtime node:24 (detected from package.json)`. Pass `--runtime` to `clone` and to `doctor --fix` to choose another.

### A repair failed

The repair line shows the error, a `Log:` path, and a `Next:` step. The build log has the full download or compile output.