Troubleshooting - Prized docs

One command diagnoses and repairs the whole chain: config, auth, tunnel, SSH, sync, daemon, and the box agent. Start here.

Run the doctor

Terminal

prized doctor

It repairs as it goes (a missing ~/Prized, Mutagen not fetched, a stopped daemon, a missing SSH Include, a box agent behind your CLI), marking each (fixed). A passing check prints nothing, so only what failed is on screen, with its remedy.

--no-fix reports without touching anything; -v prints every check; --bundle writes a diagnostics tarball for a bug report, and nothing leaves your machine.

Box and daemon

Symptom	Try
Box shows unreachable	`prized ssh`: a suspended box wakes on connect. Still down? `prized box info` and the dashboard show its state and last events.
Box paused by itself	The last event in `prized box info` says why: `reconciler:auto_pause` (idle) or `reconciler:pause_deadline`. `prized box auto-pause BOX off` and `prized box extend BOX --no-deadline` switch the rules off (Boxes).
`ssh: Could not resolve hostname <box>` from `ssh <box>` or a sync session	A box's name resolves only through the SSH stanza prized writes (`~/.ssh/config.d/prized`), activated by an `Include` line at the top of `~/.ssh/config`; your ssh did not apply it. `prized doctor` says which and repairs what it can: the line missing (or a stray pre-rename `Include config.d/doppel` that names no file this install wrote — `prized doctor --fix` adds the `config.d/prized` line), a `Host`/`Match` block above it, or an ssh that resolves the box with `-F ~/.ssh/config.d/prized` but not from `~/.ssh/config` (an alias or wrapper around `ssh`, or a HOME that is not your account's). `prized setup`, `prized ssh` and `prized exec` read the stanza file directly and keep working meanwhile; `ssh <box>` and sync need the Include.
`"<box>" is not the box this machine knew by that name` (from `ssh <box>` or a prized command)	The alias was bound to a box that no longer wears the name: the box was recreated, or its freed name was taken by another box. If that is expected, `prized box rebind <box>` binds the alias to the box that wears the name now; otherwise `prized box ls` shows what is on the account. `could not verify that "<box>" is still box …` means the check itself could not be made (signed out, or Prized unreachable): `prized login`, or try again. A `prized proxy` that was already running when the name changed hands stops with the same message; anything else still connected under that name is refused the same way until you rebind.
Daemon not running	`prized daemon restart`, then `prized daemon logs` if it will not stay up. On a machine that has never run `prized setup` there is nothing to restart yet, and the command says so: setup installs the daemon when it connects a box (`prized daemon install` does it on its own).
`prized setup` or `daemon install` says the daemon is installed for your login session and this terminal is not in it	You are in a shell outside your macOS login session (ssh, a terminal a remote tool opened, a shell either started), and the daemon on this Mac was installed from inside it, as a GUI-session agent that such a shell cannot see or touch. Run the same command from Terminal on the Mac itself. A machine that has never had the daemon is different: setup from an ssh or remote shell installs it as a background agent, which any login of yours brings up, and which Terminal on the Mac can manage too.
"the running daemon serves a different box"	You switched the default with `prized init --force` while the old daemon ran, or aimed `--config` at another box's file. `prized daemon restart` moves it.
doctor warns the daemon serves another box	`--config` drives another box with no port mirrors. Connect it with `prized setup --box NAME` and use `--box NAME` instead.
doctor reports an unpinned SSH bridge	The stanza was written by an earlier release; `prized doctor --fix` rewrites it (so do `prized login` and `prized setup`).
`no config for box NAME`	`prized setup --box NAME` connects it. A misspelled name lands here too; `prized box ls` has the right one.
doctor fails `agent-version`	Agent behind the CLI: `prized doctor` updates it (a brand-new box also catches up on its own within a minute or two). `cli behind the agent`: run `prized update`.
Claude Desktop (or another SSH app) asks for a password	The box has not received this machine's device key yet. Run `prized login` (or one `prized ssh`) here, wait a minute, retry (Claude Desktop remote).

Ports and sync

Symptom	Try
A port is not on localhost	`prized ports ls` shows every listener and why one is not mirrored. A toggled-off port stays off until you toggle it back.
Sync seems stuck	A first edit in a folder the box has not touched recently can take 10 s. Then `prized sync ls`, `prized sync flush` to force a cycle, `prized sync repair myproject` if a session halted.
Sync shows `error`	The reason is under the table and the daemon retries by itself. Fix the cause (or `prized sync rm` the project) and re-run `prized setup`.
`prized setup` says the project step failed, but the box is fine	Re-run `prized setup`; `prized sync ls` names the cause.
Mutagen reported missing	`prized doctor` fetches Prized's managed copy; so does `prized mutagen ensure`.

CLI and updates

Symptom	Try
CLI feels outdated	It updates itself; `prized update` installs the newest release now.
`prized version` warns the daemon version differs	An update landed while something was connected through the daemon; `prized daemon restart` applies it now.
Every command exits 5 with an update hint	Your CLI is older than the minimum the API supports. Run `prized update` once.
`prized: command not found` right after installing	`~/.local/bin` is not on this shell's `PATH` yet: `source` the file the installer's last line names, or open a new terminal. Windows: see Windows.
`prized: command not found` on an older install	Run `doppel update` once, or re-run the install script; either installs `prized` and keeps `doppel` as an alias.
macOS asks again for folder access after an update	`prized update` to the latest release and approve once more; releases are signed with a stable Developer ID, so macOS remembers it.
An environment item fails during setup but installs fine by hand	Re-run with `prized setup --env-workers 1` (one item at a time, in order) and `--verbose` (Bring your environment).
`ssh: not found in a trusted system directory`	Prized runs the OpenSSH client from the system directories (`/usr/bin`; `System32\OpenSSH` on Windows), never one found on `PATH`. For an ssh installed elsewhere, name it: `bin = "/path/to/ssh"` under `[ssh]` in `~/.config/prized/config.toml`.
`docker: not found in a trusted location` (or `pg_dump`, `gzip`) during the data step	The data step runs its helpers only from standard system and package-manager directories, the same places the scan looks, never from `PATH`. Install the tool there, or answer no to the data group and copy by hand.

Windows

Symptom	Try
`prized` is not recognized right after installing	A window that was already open lacks the new `PATH` entry. Open a new terminal, or run `$env:Path = "$env:LOCALAPPDATA\Prized\bin;$env:Path"` in that one.
`prized ssh` says ssh is missing	Turn on Windows OpenSSH under Settings, Optional features, OpenSSH Client, or `Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0` in an elevated PowerShell.
SmartScreen or Defender warns about `prized.exe`	The binaries are not code-signed, so Explorer can show "unrecognized app" (More info, Run anyway). If Defender quarantines it, restore it, re-run the installer, and email .
The daemon is not running, or dies after logout	`prized daemon install` re-registers and starts the `PrizedDaemon` task, which runs only while you are signed in; `prized daemon logs` has its log.
`prized daemon install` fails with an access error	A machine policy that blocks Task Scheduler for users blocks it. Run `prizedd run` in a terminal you keep open, and tell .
`prized mosh`, `mount`, or `env` refuses	Not on Windows yet (CLI); `prized ssh`, sync, ports, `exec`, and `cp` cover the same ground.

Older installs

Configs that still point at doppel.prized.dev or api.doppel.prized.dev keep working; page requests redirect to prized.dev.

Account

Symptom	Try
Sign-in fails with "unable to link account"	Your identity provider reports a different account for this address than the one Prized knows (a mailbox deleted, recreated, or reassigned). Email .
A work address that had a Prized account now starts empty	Expected if the address was reassigned to you: accounts are keyed to your identity, not the mailbox, so you get a fresh one rather than the previous holder's.

Still stuck

Email with the doctor output.

Troubleshooting.