Troubleshooting
Symptoms and their fixes, starting with the one command that checks and repairs config, auth, tunnel, SSH, sync, the daemon, and the box agent.
On this page9
Run the doctor
prized doctorIt repairs what it can (a missing ~/Prized, Mutagen not fetched, a stopped daemon, a missing SSH Include, a box agent behind your CLI) and marks each (fixed). Passing checks print nothing; each failure prints its remedy.
--no-fix only reports; -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 wakes a suspended box. Still down? prized box info or the dashboard shows its state and events. |
The browser terminal, files, desktop, a shared port or the phone says Prized could not reach BOX from its own servers | Not your network; usually the box is still starting. Reload in a minute, and email if it persists. |
open terminal failed: missing or unsuitable terminal: xterm-ghostty from prized ssh, or unknown terminal type inside a --raw shell (Ghostty) | A box adds Ghostty's terminal entry within about six hours of running (new boxes have it); meanwhile, TERM=xterm-256color prized ssh <box> connects. |
| Cmd-C copies nothing out of Claude Code | Claude handles the mouse: select, press c, and through prized ssh the text lands on your clipboard. Or drag holding Fn (Apple Terminal), Option (iTerm2) or Shift, then Cmd-C (Copy out). |
| Box paused by itself | The last event in prized box info says why: reconciler:auto_pause (idle) or reconciler:pause_deadline. Turn them off: prized box auto-pause BOX off, prized box extend BOX --no-deadline (Boxes). The idle rule never pauses a box on the free credit. |
ssh: Could not resolve hostname <box> from ssh <box> or a sync session | Your ssh skipped the Include atop ~/.ssh/config that loads the stanza prized writes (~/.ssh/config.d/prized). prized doctor says why and fixes what it can: the line missing (an old Include config.d/doppel does not count; prized doctor --fix adds the right one), a Host/Match block above it, or an ssh alias, wrapper, or HOME not your account's. Meanwhile prized setup, prized ssh and prized exec work; 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 name moved to another box (yours was recreated, or its freed name taken). If expected, prized box rebind <box> binds the alias to the box that has the name now; otherwise check prized box ls. Until you rebind, connections under the name are refused and a running prized proxy stops. could not verify that "<box>" is still box …: the check failed (signed out, or Prized unreachable); prized login, or retry. |
| Daemon not running | prized daemon restart; prized daemon logs if it will not stay up. Before your first prized setup there is no daemon: setup installs it, as does prized daemon install. |
prized setup or daemon install says the daemon is installed for your login session and this terminal is not in it | This shell (ssh, or a remote tool's terminal) is outside the macOS login session the daemon was installed from: run the command from Terminal on the Mac itself. |
| "the running daemon serves a different box" | You switched the default (prized init --force) while the old daemon ran, or aimed --config at another box's file: prized daemon restart. |
| doctor warns the daemon serves another box | --config drives another box without port mirrors. Connect it with prized setup --box NAME, then use --box NAME. |
| doctor reports an unpinned SSH bridge | An earlier release wrote the stanza: prized doctor --fix, prized login, or prized setup rewrites it. |
no config for box NAME | Connect the box here first: prized setup --box NAME (prized ssh NAME needs no config). Misspelled? prized box ls has the right name. |
session_space_exhausted or customer_session_limit when connecting to a box | No room on the box for another connection from your machine; older releases held closed ones for hours. Run prized update; still refused, email . |
Connection closed by UNKNOWN port 65535 from ssh <box> or prized ssh | The Prized bridge stopped before connecting; the prized line above says why (signed out, box unreachable, no network path, name changed hands). prized doctor checks the chain. |
doctor fails agent-version | Agent behind the CLI: prized doctor updates it (a new box catches up by itself within a minute or two). cli behind the agent: prized update. |
Codex on the box says Your access token could not be refreshed because your refresh token was already used | The box shared your machine's ChatGPT sign-in until your machine refreshed it. Run codex logout on the box, then prized agents handoff codex here (it opens the sign-in page), or codex login --device-auth on the box. |
| Claude Desktop (or another SSH app) asks for a password | The box lacks this machine's device key: run prized login (or one prized ssh) here, wait a minute, retry (Claude Desktop remote). |
Claude Desktop connects but its terminal reports PTY allocation request failed | Quit Claude Desktop fully, reopen it, and reconnect. Still failing? Contact support (Claude Desktop remote). |
Networks that block the tunnel
The CLI reaches a box over WireGuard (UDP 51820), over the same tunnel through the Prized relay (HTTPS to term.prized.dev), or over HTTPS to the box's own address. When UDP does not answer within a few seconds, it keeps whichever path answers first (box.transport_path in prized status --json) and returns to UDP once it can. prized status, prized doctor, prized setup, or any command that connects retries every path at once.
| Symptom | Try |
|---|---|
box-dial fails with no network path to the box (and prized setup stops there), or prized exec, prized ssh or prized cp stops with cannot reach BOX: no network path to the box | Every path was refused. The hint says what refused each one, including the proxy used, and what IT must allow: outbound UDP 51820 to the box's address, or WebSocket connections to term.prized.dev on port 443 without TLS inspection. Forward it as is. |
The hint says the Prized relay itself refused, or a problem on Prized's side, not your network | Not your network; nothing to ask IT. Retry in a few minutes, then email ; the code in brackets says why. |
The relay refused with relay_busy | The relay is full, for your workspace or overall. Retry in a minute; if a large team keeps hitting it, email . |
The relay refused with relay_lease_ended or relay_ticket_expired | The tunnel ended, or this device was revoked. Run the command again, after prized login if the device was revoked. |
box-dial fails with no WireGuard reply | The tunnel got through, but nothing answered; usually the box is still starting or resuming. Retry, then email . Behind TLS inspection, ask IT whether WebSocket traffic passes once connected. |
cannot reach Prized at api.prized.dev (from any command, prized setup, or doctor's cp-auth) | Your network, not your sign-in: Prized itself did not answer. Ask IT for HTTPS to api.prized.dev on port 443; the hint names the proxy used and why. |
| Your network reaches the web only through a proxy | A Mac system proxy (or an IT profile) needs nothing: the CLI, daemon, sync, and editor SSH use it. Otherwise set HTTPS_PROXY (and NO_PROXY for exceptions) and run prized setup: the daemon, sync, and editor SSH keep that proxy from any shell, going direct while it is unreachable. Precedence: HTTPS_PROXY, then the proxy prized setup recorded, then the Mac's. prized daemon proxy shows the daemon's; prized daemon proxy set URL and prized daemon proxy clear change it. Ignored, with a note, keeping the proxy the CLI had: HTTP_PROXY alone, and values that are not a proxy address (a PAC file's URL, socks://). A shell proxy replaces the recorded one only if it reaches Prized (below). SOCKS5: socks5://host:port; IPv6 in brackets; a proxy sign-in goes in the URL: http://user:password@proxy:port. |
warning: proxy: the background service keeps the proxy recorded earlier (from prized setup, prized login or a daemon command), or doctor's daemon-proxy warns that this shell's proxy did not answer | This shell's HTTPS_PROXY does not answer here, so the background service keeps its recorded proxy. Correct or unset HTTPS_PROXY; if the recorded one is stale, rerun prized setup where the new proxy answers, or prized daemon proxy set URL (it records even a proxy that does not answer from here, with a warning). |
| Your computer finds its proxy automatically, or the proxy signs in with your Windows account | Proxy auto-config (PAC) files, Windows proxy sign-in (NTLM, Kerberos), and the Windows system proxy are not supported; the hint says which it found. Diagnostics never show a PAC location (it can hold sign-in tokens). Put the proxy's address in HTTPS_PROXY and run prized setup, or ask IT to let prized.dev and term.prized.dev through without a sign-in. |
A CLI before 0.17.0 fails with expected handshake response status code 101 but got 403 | Those versions fall back only to the box's own HTTPS address, which your network refused. Run prized update; still before 0.17.0 in prized version? prized update --channel edge. |
Ports and sync
| Symptom | Try |
|---|---|
| A port is not on localhost | prized ports ls shows every listener and why one is not mirrored; a port you toggled off stays off until toggled back. |
| Sync seems stuck | A first edit in a folder the box has not touched lately can take 10 s. Then prized sync ls; prized sync flush forces a cycle; prized sync repair myproject for a halted session. |
Sync shows error | The reason is under the table, and the daemon retries. Fix the cause (or prized sync rm the project) and re-run prized setup. |
Every project is paused and you did not pause it | Your machine ran low on disk (Sync); the line under the table has the figure. Free space or ignore folders that should not travel, then prized sync resume --all. |
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 or prized mutagen ensure fetches Prized's managed copy. |
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 the daemon was in use; prized daemon restart applies it. |
| Every command exits 5 with an update hint | Your CLI is older than 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 | Re-run the install script; it 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; macOS remembers it from then on. |
| 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 ssh only from system directories (/usr/bin; System32\OpenSSH on Windows), never from PATH. For another ssh, set 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 | Data-step helpers run only from system and package-manager directories, 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 opened before the install 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 Settings, Optional features, OpenSSH Client, or run Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0 in an elevated PowerShell. |
WARNING: UNPROTECTED PRIVATE KEY FILE, or "permissions are too open" | Windows OpenSSH refuses a key another account can read, usually after a tool (Codex's sandbox) gave a group access under %LOCALAPPDATA%. prized doctor or the next prized login cuts %LOCALAPPDATA%\Prized\id_prized back to your account, SYSTEM, and Administrators. |
SmartScreen or Defender warns about prized.exe | The binaries are not code-signed: choose 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 blocks Task Scheduler for users. 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 Prized knows (mailbox deleted, recreated, or reassigned): email . |
| Every box paused and the dashboard says the workspace is suspended or paused | The message says why. On the free credit, one process holding the whole box at full CPU for over 30 minutes pauses the workspace: start a plan and wake the box. Mining: Not allowed. Mistaken? Email . |
| A work address that had a Prized account now starts empty | Expected if the address was reassigned to you: accounts follow your identity, not the mailbox, so you never inherit the previous holder's. |
Still stuck
Email with the doctor output.