Every error is one line:
Failed: <cause> — fix: <action>The action is a command or one thing to change. A retry of the same command is safe. The tables list the cause. The line also prints the fix.
Two commands help with most problems:
cf-opencode doctorchecks this machine, the install and the Worker. It starts nothing.cf-opencode logs <workspace>prints the redactedopencode servelog.
init and upgrade
init checks everything first and prints every problem at once.
| Cause | What to do |
|---|---|
Node … is too old; cf-opencode needs Node 22 or later |
Install Node 22 or newer. Run init again. |
bad Worker name … |
Use lowercase letters, digits and -, up to 63 characters. |
Docker is not running (wrangler builds the workspace image locally) |
Start Docker. Check docker info. Run init again. |
Docker has no buildx plugin … |
Install buildx. On Debian or Ubuntu, run apt install docker-buildx-plugin. Check docker buildx version. |
wrangler is not logged in to Cloudflare or not logged in to Cloudflare or wrangler is not logged in, or the token lacks Workers Scripts Write and Workers Containers Write |
Run npx wrangler login, or set CLOUDFLARE_API_TOKEN. Run init again. |
Cloudflare rejected the API token |
Create a token with Workers Scripts Write and Workers Containers Write. Run init again. |
account … is not one this login can see |
Pass an ID that npx wrangler whoami lists. |
this login lists no Cloudflare accounts |
Pass --account <id>, or log in with an account that has Workers Paid. |
this login has N Cloudflare accounts |
Pass --account <id> or set CLOUDFLARE_ACCOUNT_ID. On a terminal, init asks you to pick one. |
Containers need the Workers Paid plan on this account |
Upgrade the account to Workers Paid. Run init again. |
a Worker named … already exists in this account, and this machine did not deploy it |
Pass --name <other> for a separate install. Or pass --adopt to replace it. --adopt changes its control token. |
this account has no workers.dev subdomain yet |
Open the Workers page of the dashboard once. It creates a subdomain. Run init again. |
wrangler deploy did not finish in … minutes |
Check your connection. Run init again. Pushed layers stay. |
wrangler deploy kept failing on a transient error … |
Run init again. If it repeats, read ~/.cf-opencode/deploy.log. |
wrangler deploy failed: … |
Fix the error that the line shows. Run init again. |
wrangler deploy did not print a workers.dev URL |
Enable workers.dev for the Worker in the dashboard. Run cf-opencode init --url <url>. Or deploy with --domain <hostname>. |
--domain … is not a hostname or --domain … is a workers.dev hostname |
Pass only a hostname in a zone of your account, for example code.example.com. |
no zone for <hostname> in this Cloudflare account or wrangler found no zone for the --domain hostname in this account |
Add the domain to the account. Or pass --account <id> of the account that has the zone. Or pass another --domain. |
the zone … is pending, not active |
Finish the zone setup in the dashboard. Set the nameservers at your registrar. |
<hostname> has DNS records (…), and the deploy replaces them |
Delete the records in the dashboard. Or pass another --domain. Or pass --adopt to replace them. |
<hostname> is a Custom Domain of the Worker … |
Pass another --domain. Or pass --adopt to move the hostname to this install. |
--url and --domain do not go together |
Pass --domain to deploy on a hostname. Pass --url to use a Worker that is deployed. |
deployed, but the control token was not stored: … |
Run init again. It reuses the same token. |
the Worker did not accept the control token: … |
Wait a minute. Run cf-opencode doctor. |
cannot read a token from <path> |
Write the API token to that file, mode 600. Run init again. |
--url "…" is not a URL or --url "…" is not an https Worker URL |
Pass only the origin, for example https://code.example.com. No path. |
no control token for that Worker |
Copy ~/.cf-opencode/control-token from the machine that ran init. Or set CF_OPENCODE_CONTROL_TOKEN. |
nothing to upgrade on this machine |
Run cf-opencode init. |
On a first run that failed after it created the Worker, ~/.cf-opencode/deploying.json lets the rerun finish without --adopt.
run and tasks
| Cause | What to do |
|---|---|
local checkout <path>: … with … not pushed to origin/<branch>, branch <branch> is not pushed (no upstream), HEAD is not on a branch, N files with changes not committed or N untracked files, followed by the workspace clones from the Git remote and would not see this |
Commit and git push in that checkout on your machine, or pass --allow-dirty. These are the preflight failures of run. The preflight reads your machine, not the workspace: a clean tree in the workspace does not change it. |
tasks shows done !, or a task shows Not pushed ! or Processes ! |
The task ended with commits that are only in the workspace, or with a process that the next pause stops. Run the --reply command that tasks <ses_…> prints. See Work that is not safe. |
the task is empty or run needs a task |
Give the task as one quoted argument. |
run takes the task as one argument |
Put the task in quotes. |
<file> is outside the supported JSON Schema subset (…) |
Use only type, properties, required, items, enum and additionalProperties: false in --schema. |
<file> is not JSON, cannot read <file> (…) or <file> is over 8000 characters |
Fix the schema file. |
bad --timeout <value> |
Pass a number of minutes, for example --timeout 90. |
--wait and --follow do the same wait |
Pass one of them. |
--wait needs one task or --follow needs one task |
Give a ses_… ID. |
no task <ses_…> in the workspaces of this machine |
Run cf-opencode tasks. Pass --workspace <id> for another workspace. |
task <ses_…> is in <a> and <b> |
Pass --workspace <id>. |
workspace <workspace> is not running, so task <ses_…> cannot finish |
The workspace stopped under the task. Run cf-opencode connect <workspace> --session <ses_…>. |
<cause>; the state of task <ses_…> is not known |
The Worker gave an error three times. The task is not lost. Run cf-opencode tasks <ses_…> again. |
no answer from the Worker for N min; the state of task <ses_…> is not known, and the task goes on in the workspace |
Your machine could not reach the Worker for 5 minutes. The task is not affected. Check the network, then run the --wait command again. The exit code is 3. |
task <ses_…> still runs after N min |
Wait again with the same command. The exit code is 3. |
--reply needs one task |
Give a ses_… ID: cf-opencode tasks <session> --reply "<text>". |
the reply is empty or the reply is over 20000 characters |
Change the text of the reply. |
no session <ses_…> in <workspace> |
Run cf-opencode tasks. |
no access to <workspace> |
Run cf-opencode connect <workspace> --no-attach, then retry. |
OpenCode refused the reply (HTTP <code>) |
Run cf-opencode logs <workspace>. |
Notify URL
| Cause | What to do |
|---|---|
no URL given |
Pipe the URL in: printf %s "$URL" | cf-opencode notify-url. |
the URL must start with https://, the URL is not a URL, or the URL must name a public host, not an IP address, localhost or an internal name |
Give an https URL of your receiver. |
the URL must not hold a user or password; the POST is signed instead |
Remove the user and password from the URL. |
no notify URL is set |
The note or delivery has no target. Run cf-opencode notify-url. |
this workspace sent 20 notes in the last hour |
Wait, and send fewer notes. |
notifyUrl in <path> is no longer a setting; the URL is a Worker secret now |
Remove notifyUrl from the file. Run cf-opencode notify-url. |
could not delete the secret: … |
Run npx wrangler login, then retry. |
Skills and completion
| Cause | What to do |
|---|---|
no skill <name> on this machine |
Run cf-opencode skills to list the names. |
skill <name> is N MB, over the 5 MB limit |
Remove large files from the skill, or copy it by hand with cf-opencode ssh. |
skills push needs skill names |
Name the skills, or pass --all. Or set a list with cf-opencode skills default. |
skills remove needs skill names |
Name the skills to remove. |
no skills on this machine |
Put a skill folder with a SKILL.md in ~/.config/opencode/skills. |
bad skill name … |
Rename the skill folder. A name has letters, digits, ., _ and -, at most 64 characters. |
unknown skills action <word> |
Use push, remove or default. |
the workspace command failed (ssh exit <code>) |
Run cf-opencode connect <workspace>, then retry. |
<path> exists and differs from this version |
cf-opencode skill --install does not replace a file that differs. Pass --force. |
--install needs one place |
Pass one of --claude, --opencode or --dir <skills folder>. |
--claude, --opencode and --dir go with --install |
Add --install. |
completion needs a shell or no completion for "<shell>" |
Use bash, zsh or fish. |
MCP
| Cause | What to do |
|---|---|
<dir> is outside the folder this MCP server started in |
Start the MCP server in that project, or leave directory out. |
<dir> is not a git checkout |
Pass directory (a git checkout) or workspace. |
session must be a ses_… id |
Pass the session that handoff_task returned. |
task is empty |
Pass the full task brief as task. |
GitHub
| Cause | What to do |
|---|---|
no GitHub token on the Worker: a private repository will not clone, and push will fail |
Run gh auth token | cf-opencode git-token. |
GitHub rejected that token |
Create a new token. Run cf-opencode git-token again. |
no token given |
Pipe a token in, or run cf-opencode git-token on a terminal. |
could not store the secret: … |
Run npx wrangler login. Run git-token again. |
repo prepare failed: … |
Check the git URL. For a private GitHub repository, run cf-opencode git-token. |
connect and workspaces
| Cause | What to do |
|---|---|
no Worker URL |
Run cf-opencode init, or pass --url. |
no control token |
Run cf-opencode init. It writes ~/.cf-opencode/control-token. |
OpenCode is not installed here |
Install OpenCode 2: curl -fsSL https://opencode.ai/v2/install | bash. |
cannot reach <url> from this machine (fetch failed); workspaces and their tasks are not affected |
A connection from your machine dropped. Tasks in the workspaces go on. Run the command again. If it repeats, check the network and run cf-opencode doctor. --wait and --follow try again by themselves for 5 minutes. |
Every command fails with cannot reach <url> or answered HTTP 404 … with a page after the workers.dev subdomain of the account changed |
The install on this machine has the old URL. Run cf-opencode doctor. It finds the Worker and prints the fix, cf-opencode init --url https://<worker>.<new subdomain>.workers.dev. Run it. It deploys nothing, and the control token does not change. A Host block that ssh-config printed without --url reads the new URL. Replace a block that has --url in it. To stop this from happening again, put the Worker on your own hostname: cf-opencode upgrade --domain <hostname>. |
doctor prints Worker … is in the account with no URL |
The Worker exists, but doctor did not find a URL that answers. Find the URL in the dashboard, under Workers & Pages, the Worker, Settings, Domains & Routes. Run cf-opencode init --url <url>. |
doctor prints Worker … is not in the account |
The Worker is gone. Run cf-opencode init. |
init prints ! https://<hostname> does not answer yet |
A new Custom Domain can take some minutes. The install is saved. Run cf-opencode doctor later. |
the Worker refused the control token on this machine |
The control token on this machine differs from the Worker. Copy ~/.cf-opencode/control-token from the machine that ran init, or run cf-opencode init --adopt. |
N/M workspaces already running |
Pause an idle workspace with cf-opencode pause <workspace>. Or raise maxRunning in ~/.cf-opencode/config.json and run cf-opencode upgrade. |
spawn did not finish in 4 min 30 s |
Retry. Check cf-opencode status <workspace>. |
container was not ready in time |
Retry. The first start on a new host pulls the image and is slow. |
container failed to start: … |
Run cf-opencode logs <workspace>. |
snapshot not found |
The disk snapshot is gone. Run cf-opencode delete <workspace>, then cf-opencode connect. The workspace starts from the image. |
opencode serve did not start: … |
Run cf-opencode logs <workspace>. |
opencode did not answer /api/info in … s |
Run cf-opencode logs <workspace>. |
control plane restarted during … |
Wait. The connect retries. If it repeats, run cf-opencode logs <workspace>. |
A deploy restarts the Durable Object of a workspace. If that interrupts a connect, the CLI prints the Worker restarted (a deploy); trying once more.
Shell, SSH and browse
| Cause | What to do |
|---|---|
no local password for <workspace> |
Run cf-opencode connect <workspace>. |
<ses_…> is a session id, not a workspace |
Give the workspace first: cf-opencode connect <workspace> --session <ses_…>. To read a task: cf-opencode tasks <ses_…>. |
the workspace refused the password for <workspace> |
Run cf-opencode connect <workspace>. |
<workspace> was deleted |
Start a new workspace with cf-opencode connect. |
<workspace> did not wake (<status>) |
Run cf-opencode logs <workspace>. |
Connection timed out during banner exchange from ssh or scp |
Your SSH config has a short ConnectTimeout for all hosts, and the wake of a paused workspace takes longer. cf-opencode ssh sets 120 seconds from 0.3.0. For a Host block that an older version printed, remove it from ~/.ssh/config and run cf-opencode ssh-config <workspace> >> ~/.ssh/config again. |
the Origin header is not this Worker's origin (HTTP 403 on a websocket) |
Your client library adds an Origin header by itself. Send none. In Python: websocket.create_connection(url, header=[…], suppress_origin=True). A workspace made before 0.3.0 has the old Python library: use suppress_origin=True there, or run cf-opencode rebuild <workspace>. |
the shell websocket was refused (<code>) |
Run cf-opencode logs <workspace>. |
the ssh websocket was refused (<code>) |
Run cf-opencode logs <workspace>. |
<workspace> is paused, and a dev server does not survive a pause |
A --web preview does not wake a paused workspace. Run cf-opencode connect <workspace>, start the dev server, then retry. The default cf-opencode preview wakes it. |
shell needs an interactive terminal |
Use cf-opencode ssh <workspace> -- <command> in a script. |
ssh is not installed here |
Install OpenSSH. |
ssh-keygen failed |
Install OpenSSH (ssh and ssh-keygen). |
this Worker has no Browser Run binding |
Run cf-opencode init to redeploy. |
Browser Run refused a session (…) |
Retry cf-opencode browse. |
browser session … refused the connection (<status>) or … is gone (…) |
Open a new session with cf-opencode browse. |
If ssh says the host key changed, remove the line for cf-opencode-<workspace> from ~/.cf-opencode/ssh/known_hosts.
Pause, rebuild and delete
| Cause | What to do |
|---|---|
snapshot failed after N attempts (…) |
Retry the pause. Check cf-opencode status <workspace>. |
project snapshot … not saved (…); workspace left running |
Retry the pause. Check cf-opencode status <workspace>. |
this workspace has no disk to carry |
Run cf-opencode connect <workspace>. It boots the new image. |
the old disk did not start (…), tar on the old disk exited …, rebuild failed: … |
Retry. The old disk is unchanged. |
the new image did not start (…), unpacking on the new image exited … |
Retry. |
no image in this deploy |
Run cf-opencode upgrade. |
no such workspace |
Run cf-opencode connect. |
Configuration
| Cause | What to do |
|---|---|
config.json is not JSON or must hold one JSON object |
The settings file is wrong. Correct ~/.cf-opencode/config.json, or delete it to use the defaults. Then run cf-opencode upgrade. |
<key> must be an integer from <min> to <max> |
Use a value in that range. See Configuration. |
alarmSeconds … must be shorter than inactivityTimeoutMinutes |
Lower alarmSeconds, or raise inactivityTimeoutMinutes. |
instance … is not a container size |
Use standard-1, standard-2, standard-3 or standard-4. |
Install state
| Cause | What to do |
|---|---|
no install on this machine |
Run cf-opencode init. |
wrangler could not list containers: … |
Run npx wrangler login. Run uninstall again. |
N delete(s) failed |
Run cf-opencode uninstall --yes again. It skips deleted items. |
the Worker sources are missing from this install |
Reinstall cf-opencode, or run npm run build -w cli in a checkout. |
unknown command … |
Run cf-opencode --help. |