---
title: "Troubleshooting"
description: "The Failed lines that cf-opencode prints, what each one means, and the fix."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode.system3inference.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

Every error is one line:

```text
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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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](https://cf-opencode.system3inference.dev/docs/reference/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`. |

Source: https://cf-opencode.system3inference.dev/docs/troubleshooting/index.mdx
