Skip to content

Troubleshooting

Run doctor, and fix the most common Failed lines.

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

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.

Settings

A bad setting fails with Failed: <key> must be … — fix: set it in ~/.skyworker/config.json, then skyworker upgrade. See Configuration.

Still stuck

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

Type to search…

↑↓ navigate↵ selectEsc close