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 page12
If Prized itself looks down, check prized.dev/status first: it shows whether the website and dashboard, the API and the browser terminal are up, and any incidents.
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.
Editor or ssh says the box is not running
The box is asleep. Wake it, then reconnect:
prized box resume BOX --wait- Why: it paused itself after sitting idle (2 hours by default on the free credit), or it was paused. Plain
ssh, VS Code or Cursor Remote-SSH, and sync do not wake it; they fail withbox not running (state "suspended")in their output or log. - Other ways to wake it:
prized ssh,prized exec,prized up, or Resume on the dashboard (Pause and resume). - Sync retries by itself and catches up once the box runs.
- Change or stop the sleep:
prized box auto-pause BOX 4h(30m to 7d) orprized box auto-pause BOX off, or Auto-pause on the box's dashboard page. A box on the free credit never sleeps in its first 24 hours.
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. |
BOX is paused because your free credit ran out (or your credit ran out) from ssh <box>, an editor, sync, prized ssh or prized up | The balance is empty, so no wake can start the box. Nothing was deleted: its disk is kept. Pick a plan or add credit at the link the message prints (Running out); boxes the stop paused start again on their own, and editors and sync reconnect once the box runs. |
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). On the free credit, a box pauses after 2 hours idle unless you changed that, never in its first 24 hours. |
Editor or ssh cannot connect: box not running | The box is paused: prized box resume BOX --wait, then reconnect (Editor or ssh says the box is not running). |
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 …: you are signed out, or Prized stayed unreachable (offline; right after a wake, the connection first waits a few seconds for the network); prized login, or retry once online. |
| 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. |
| Daemon gone after a reboot on Linux without systemd (WSL, a container) | With no systemd user session, prized runs the daemon itself and nothing brings it back: prized doctor starts it again. On WSL, turning systemd on (systemd=true under [boot] in /etc/wsl.conf, then wsl --shutdown) and running prized daemon install makes it start on its own. |
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. |
prized setup, prized up or prized ssh says box "OLD" is terminated or no box "OLD" on your account, after you deleted that box or signed in to another account | This machine is still set up for the old box, and prized login and prized setup keep an existing config. If --box OLD or PRIZED_BOX names the old box, drop or unset it. With no box left, prized box new first. prized init --force --box NAME makes one of your boxes this machine's default (the old config is backed up first); then run prized setup in your project again. If the failing command names its config with --config FILE or PRIZED_CONFIG, switch that file instead: prized --config FILE init --force --box NAME. A box's own boxes/OLD.toml can't be moved to another box; use the default config or NAME's own instead. A box already connected here with its own config needs no switch: run the command the hint prints for it (usually prized ssh NAME or prized setup --box NAME; --config PATH when its config is somewhere --box doesn't look). |
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. |
| The phone connection closes during sign-in | The gateway may be busy. Wait briefly and reconnect with the same phone password. If it keeps failing, check the host, port, username and current password in the box’s Phone access settings (From your phone). |
| 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. Otherwise set HTTPS_PROXY (and NO_PROXY for exceptions) and run prized setup (Proxy settings). |
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. |
Proxy settings
- What uses it: the CLI, daemon, sync, and editor SSH. After
prized setup, the daemon, sync, and editor SSH keep the proxy from any shell, going direct while it is unreachable. - Precedence:
HTTPS_PROXY, then the proxyprized setuprecorded, then the Mac's. A shell proxy replaces the recorded one only if it reaches Prized (thekeeps the proxy recorded earlierwarning above). - See or change it:
prized daemon proxyshows the daemon's;prized daemon proxy set URLandprized daemon proxy clearchange it. - Ignored, with a note:
HTTP_PROXYalone, and values that are not a proxy address (a PAC file's URL,socks://); the CLI keeps the proxy it had. - Formats: SOCKS5 as
socks5://host:port; IPv6 in brackets; a proxy sign-in goes in the URL:http:/./ user:password@proxy:port
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 | prized sync ls names the cause. If the sync could not be created, re-run prized setup the same way: it tries again at once. A halted project needs prized sync repair myproject, a paused one prized sync resume myproject. |
| Mutagen reported missing | prized doctor or prized mutagen ensure fetches Prized's managed copy. If your network cannot download it, the error names the file: download it in a browser, then run prized mutagen ensure --from <file> and re-run prized setup. |
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. |
this API key has expired (exit 8), or 401 token_expired from the API or the edge | The key ran out. On a machine (its key expires after 180 days unused), run prized login. A key from New key: make a new one under Settings → API keys and replace it where it runs (When a key expires). |
A script's key answers 404 not_found for a box the dashboard shows, or 403 key_access_denied with scope: "boxes" | The key is limited to other boxes, or the route reaches the whole workspace (Limit a key to some boxes). Make a key for that box, or one without a box limit. |
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. |
A Go tool is not carried after setup | The reason is in the env row. One the box could not download (a private module, or code that was never pushed): build it on the box from a checkout of its repo with go install ./.... One that does not build on Linux: use a Linux build of it, or an alternative. |
| 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 ~/. |
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. |
Sandboxes
| Symptom | Try |
|---|---|
429 sandbox_quota_exceeded or 422 invalid_resources with "tier": "free" | A free-tier limit: 4 sandboxes, 2 vCPU and 4 GB each, 60 minutes. A top-up or a plan lifts the workspace to the full quotas. |
409 paid_balance_required on a create, resume, or fork | Free-tier access is switched off for your workspace, and it has only free credit. Start a plan or buy a top-up, then retry. |
409 insufficient_balance | The balance is empty: add credit. Sandboxes that paused when it ran out stay paused until you resume them. |
409 workspace_held | The workspace is on hold, and its running sandboxes and boxes were paused; the message says why (Not allowed). Pausing and deleting still work. Mistaken? Email . |
409 workspace_closing | The workspace is being closed. The owner can reopen it (Close or erase the workspace). |
429 sandbox_quota_exceeded | reason names the quota. Paused sandboxes hold their vCPU and memory, so delete the ones you are done with (Limits: Sandboxes). |
403 key_access_denied | The key lacks Sandboxes: Write (or Read for lists), or is limited to some boxes. Make a key with sandbox access under Settings → API keys. |
404 not_found on every sandbox route | The key belongs to a contractor, or to another workspace. |
409 sandbox_not_running from a command or file request | Read the sandbox's state. resizing: the resize ends on its own; retry once it leaves resizing. error: it will not run again, and errorReason says why; delete it and create another. deleting: it is going away. paused, starting, or pausing: the request sent Prized-Auto-Resume: false, which answers 409 whenever the sandbox is not running. Drop the header and the request waits for it, waking a paused one (Pause and resume); or keep it, resume a paused one yourself, and retry once the sandbox reads running. |
503 sandbox_not_ready from a command or file request | The sandbox was paused or starting and did not reach running within the edge's 10-second wait (The edge). Nothing ran; retry. |
502 sandbox_unreachable | The sandbox did not answer: usually it had just started or resumed. Retry, but a command that got this may already have run. |
A sandbox sits in starting | Capacity is being added at a busy moment; it usually clears by itself. If it ends in error, delete it and create another. |
A sandbox is in error | errorReason says why. It costs nothing and is removed after autoDeleteMin, or an hour; create another. |
| A sandbox is gone | It reached its maxRuntimeMin, or autoDeleteMin after a pause; both erase it (Automatic pause and delete). |
pip install or npm install -g says permission denied | The sandbox user has no root. Use a venv (python3 -m venv .venv), or npm config set prefix ~/.local first (Inside a sandbox). |
409 fork_capacity | The parent's machine has room for only fits more copies, and how many fit depends on the shape (Fork). Fork that many or fewer if fits is above 0, try again later, or start a new sandbox and fork that, keeping the parent until the new one runs: new sandboxes start, when they can, where there is room to fork them. The new sandbox and each copy count toward your quota (the free tier allows 4 at once): at the limit, delete sandboxes you no longer need and wait until prized sandbox ls no longer lists them, or raise it: on the free tier by topping up, otherwise by emailing . Copy out what you need before you delete one, and never delete a parent while a copy forked from it is still starting. |
503 sandbox_capacity | No sandbox capacity is free right now; nothing was created or billed. Retry after the Retry-After seconds. |
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.