---
title: "Troubleshooting"
description: "Run doctor, and fix the most common Failed lines."
---

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

# Troubleshooting

An error of the CLI is one line: `Failed: <cause> — fix: <action>`. Do the action, then run the same command again. A rerun of `init` is safe. It keeps the control token.

## Run doctor

```sh
skyworker doctor
```

`doctor` checks Node, OpenCode, `ssh`, the Worker URL, the control token, the web client and the Worker. It checks the model binding, the Browser Run binding, GitHub and the notify URL. It starts no workspace.

| Mark | Meaning |
| --- | --- |
| `✓` | The check passed. |
| `!` | A warning. The line has a fix. |
| `✗` | A failure. The line has a fix. The exit code is 1. |

`doctor` fails when OpenCode is not installed, because `connect` needs it. If you use only `run` and `tasks`, you can ignore that line. OpenCode 2 is the supported version. Install it with `curl -fsSL https://opencode.ai/v2/install | bash`.

If the Worker URL moved, for example after a change of the workers.dev subdomain, `doctor` prints `skyworker init --url <new url>`. That command deploys nothing.

`skyworker doctor --json` prints the checks as JSON.

## Install and login

| Line | What to do |
| --- | --- |
| `Failed: no licence key on this machine — fix: run skyworker login, or set SKYWORKER_LICENSE_KEY` | Run `skyworker login`. |
| `Failed: that is not a licence key — fix: copy the whole key; it starts with skl_` | Copy the whole key and run `skyworker login` again. |
| `Failed: the key is not an argument …` | Do not type the key after `login`. Run `skyworker login` and paste it, or pipe it in. |

## Init

`init` prints every problem of the machine at once.

| Cause | What to do |
| --- | --- |
| `Node <version> is too old; skyworker needs Node 22 or later` | Install Node 22 or newer. |
| `Docker is not running` | Start Docker. Check `docker info`. |
| `Docker has no buildx plugin` | Install it. On Debian or Ubuntu, `apt install docker-buildx-plugin`. Check `docker buildx version`. |
| `wrangler is not logged in to Cloudflare` | Run `npx wrangler login`, or set `CLOUDFLARE_API_TOKEN`. |
| `Cloudflare rejected the API token` | Make a token with Workers Scripts Write and Workers Containers Write. |
| `this login has N Cloudflare accounts` | Pass `--account <id>` or set `CLOUDFLARE_ACCOUNT_ID`. |
| `Containers need the Workers Paid plan on this account` | Move the account to the Workers Paid plan, then run `init` again. |
| `this account has no workers.dev subdomain yet` | Open the Workers page of the dashboard once. It makes one. Then run `init` again. |
| `a Worker named <name> 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 the control token of that Worker. |
| `the Worker did not accept the control token` | Wait a minute, then run `skyworker doctor`. |
| `wrangler deploy kept failing on a transient error` | Run `init` again. Pushed layers are kept. If it repeats, read `~/.skyworker/deploy.log`. |
| `wrangler found no zone for the --domain hostname in this account` | Add the domain to this Cloudflare account, or pass another `--domain`. |

## Run a command

| Cause | What to do |
| --- | --- |
| `no Worker URL` | Run `skyworker init`, or pass `--url`. |
| `no control token` | `init` writes `~/.skyworker/control-token`. Copy it from the machine that ran `init`. |
| `the Worker refused the control token on this machine` | Copy `~/.skyworker/control-token` from the machine that ran `init`. Or run `skyworker init --adopt`. |
| `no control token for that Worker` | You ran `init --url`. Copy the control token file, or set `SKYWORKER_CONTROL_TOKEN`. |
| `OpenCode is not installed here` | Install OpenCode 2. `connect` needs it. |
| `<id> is a session id, not a workspace` | Use `skyworker connect <workspace> --session <id>`, or `skyworker tasks <id>`. |
| `no local password for <id>` | Run `skyworker connect <id>` once on this machine. |
| `<id> was deleted` | Start a new workspace with `skyworker connect`. |
| `this install has no app Worker yet` | Run `skyworker upgrade`, then `skyworker pair`. |

## run

| Cause | What to do |
| --- | --- |
| `… the workspace clones from the Git remote and would not see this` | Commit and `git push`, or pass `--allow-dirty`. |
| `branch <name> is not on origin, and the workspace starts from origin` | Run `git push -u origin <name>`, or pass `--branch` with a branch that is on origin. |
| `the checkout <dir> has no remote origin` | Run `git remote add origin <url>`, then `git push`. |
| `<n>/<m> workspaces already running` | Pause an idle workspace, or raise `maxRunning` in `~/.skyworker/config.json` and run `skyworker upgrade`. |
| `--new and --worktree both give the task its own checkout` | Pass one of them. |
| `unknown harness <name>` | Use `opencode`, `claude-code` or `codex`. |
| `no task <session> in the workspaces of this machine` | Run `skyworker tasks` to list them. Pass `--workspace <id>` for another. |

A second task in a checkout that a task already uses is refused. Use `--worktree` or `--new`. See [Run tasks](https://skyworker.system3inference.dev/docs/guides/tasks/#run-two-tasks-at-once).

## Settings

A bad setting fails with `Failed: <key> must be … — fix: set it in ~/.skyworker/config.json, then skyworker upgrade`. See [Configuration](https://skyworker.system3inference.dev/docs/reference/configuration/).

## Still stuck

Read the log of a workspace: `skyworker logs <workspace>`. Read the deploy log: `~/.skyworker/deploy.log`.

Source: https://skyworker.system3inference.dev/docs/troubleshooting/index.mdx
