Skip to content

Troubleshooting

The Failed lines that cf-opencode prints, what each one means, and the fix.

Updated

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 doctor checks this machine, the install and the Worker. It starts nothing.
  • cf-opencode logs <workspace> prints the redacted opencode serve log.

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.

Type to search…

↑↓ navigate↵ selectEsc close