---
title: "Troubleshooting"
description: "Error messages from cf-orbs, with the cause and the fix for each."
---

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

# Troubleshooting

Find your error message in the tables below. With no message yet, start with `npx cf-orbs doctor`. It checks the install and never starts anything.

Every cf-orbs error is one line:

```text
Failed: <cause> — fix: <action>
```

Do the action, then run the same command again. `init` and `deploy` are safe to run again.

## Install and deploy

| You see | Cause and fix |
| --- | --- |
| `Node <version> is too old; cf-orbs needs Node 22 or later` | Install Node 22 or later, then run the command again |
| `Docker is not running (wrangler builds the orb image locally)` | Start Docker, check `docker info`, and run again. To install without Docker, use [Workers Builds](/docs/guides/install-workers-builds/) |
| `wrangler is not logged in to Cloudflare` | Run `npx wrangler login`, then run again |
| `wrangler is not logged in or the token lacks permissions` | Run `npx wrangler login`, then run again |
| `wrangler whoami lists no accounts` | Log in with an account that has Workers Paid |
| `this login has N Cloudflare accounts` | Add `--account-id <id>`, or set `CLOUDFLARE_ACCOUNT_ID` |
| `account <id> is not in wrangler whoami` | Pass an account id that `npx wrangler whoami` lists |
| `Containers need the Workers Paid plan on this account` | Upgrade the account to Workers Paid, then run the same command again |
| `this account has no workers.dev subdomain yet` | Run `init` in a terminal (it asks), or add `--subdomain <name>` |
| `plan check skipped (wrangler containers list failed: ...)` | A warning only. The plan check is best effort, and the deploy fails with a clear message if the plan is wrong |
| `registry push timed out` or `image preparation returned 401`, with `retry n of 3` | Nothing. `init` and `deploy` retry by themselves |
| `image push to registry.cloudflare.com kept failing (timeout or 401)` | Run `cf-orbs deploy` again. The registry keeps the layers it has |
| `wrangler deploy failed: <last error line>` | Fix the error that wrangler shows, then run `cf-orbs deploy` again |
| `deploy finished but no workers.dev URL was printed` | Pass `--url https://<name>.<subdomain>.workers.dev` to `status` and `doctor` |
| `image Dockerfile missing: <files>` | Create the file, or remove its key from `images` in the config |
| `CLI templates missing at <path>` | Reinstall cf-orbs. In a source checkout, run `npm run build -w cli` |
| `cf-orbs.config.jsonc is not valid JSONC (...)` | Fix the syntax in the config |
| `unknown key "<key>" in cf-orbs.config.jsonc` | Remove it, or check the spelling against the [config reference](/docs/reference/config/) |
| `<key> must be ...` | A value is out of range. Edit the config, then run `cf-orbs deploy` |
| `fastTmpfsGb <n> leaves less than 3 GiB of the orb's <m> GiB memory` | Lower `fastTmpfsGb` to the number in the fix line |
| `instance <name> is too small for the orb image` | Set `instance` to `standard-1` or larger |
| `--no-deploy supports only --provider cloudflare` | Drop `--provider external`, or run `init` without `--no-deploy` |
| `Worker <name> already exists in this account and this folder did not create it` | Cause: this folder has no saved deployment, and a Worker with this name is in the account. A deploy would replace its control token, config and image. Fix: run `init` in the folder that made it, restore that folder (see [Back up and restore](/docs/guides/back-up-and-restore/)), pass `--name <new>` for a second install, or pass `--adopt` to take it over |
| `existing-Worker check could not run (...)` | A warning only. The check is best effort, so `init` goes on. Check your network and `npx wrangler whoami` |
| `--vcpu must be 1, 2, 3 or 4` | Pass `--vcpu 4` (default) or `--vcpu 2` |

## Tokens and the provider

| You see | Cause and fix |
| --- | --- |
| `no Amp provider token given` | Set `AMP_ORB_PROVIDER_TOKEN`, or pass `--token-file <file>`. Make the token in Amp → Settings → Orbs → Add Provider |
| `the Amp provider token is empty` or `contains spaces or newlines` | Copy only the token value from Amp |
| `token file <file> not found` | Pass the path to a file that holds the `aop_live_` token |
| `no Amp provider token (the Worker has none after external mode)` | Set `AMP_ORB_PROVIDER_TOKEN` or add `--token-file` |
| `Amp rejected the provider token (wrong or revoked)` | Make a new token in Amp, then run `cf-orbs init --token-file <file>` |
| `another amp orb provider already uses this token, so this one takes no jobs` | Two providers run on one token. Stop the other one or use a separate token, then run `init` again |
| `provider did not report running within <n> s` | Run `cf-orbs logs --provider`. The 5-min cron retries the start, so run `cf-orbs doctor` again in a few minutes |
| `the Worker has no AMP_ORB_PROVIDER_TOKEN secret, so it runs no provider` (doctor) | Run `cf-orbs init --token-file <file>` |
| `providerHost is external but the Worker's own provider is running too (two providers on one token)` (doctor) | Run `npx wrangler secret delete AMP_ORB_PROVIDER_TOKEN --config .cf-orbs/wrangler.jsonc` |
| `control token rejected (401)` | Run `cf-orbs deploy` to send the token in `.cf-orbs/control-token` again |
| `route not found (404); the public API is off or the Worker is old` | Run `cf-orbs deploy`. For a Workers Builds project, wait for the first build |
| `no control token in <path>` | Run `cf-orbs init` in this directory |
| `<path> has mode <mode>` (doctor, control token) | Run `chmod 600 .cf-orbs/control-token` |
| `no control-plane URL in <path>` | Run `cf-orbs init` or `deploy`, or pass `--url` |
| `cannot reach <url> (...)` | Check your network. Run `cf-orbs doctor` |
| `orb self-test failed: no instance started from the new image` | Run `cf-orbs logs --provider` and `cf-orbs status`, check the image build, then run `cf-orbs deploy` |
| `self-test: still running after 3 min` | A warning only. The first start on a new host pulls the image. Check `cf-orbs status` |

## Orbs and threads

| You see | Cause and fix |
| --- | --- |
| An orb does not start | Run `cf-orbs logs <orb>` and `cf-orbs status <orb>` |
| `<n>/<max> orbs already running` | Raise `maxRunning`, or let idle threads pause |
| `spawn did not finish in 4 min 30 s` | Send the message again, and check `cf-orbs status <orb>` |
| `container did not become ready in <n> s` | Send the message again, and check `cf-orbs status <orb>` |
| `amp orb bootstrap did not connect in <n> s` | Check that no other provider uses this token, and run `cf-orbs logs <orb>` |
| `amp orb bootstrap stopped before it connected (...)` | Read the log lines above it, and run `cf-orbs logs <orb>` |
| `control plane did not finish <op> within 270 s` | The `dispatch.sh` deadline. Run `cf-orbs logs <orb>` |
| `control plane restarted during <op>; the job will be retried by Amp` | No action needed. If it repeats, run `cf-orbs logs <orb>` |
| `snapshot failed after <n> attempts (...)` or `project snapshot <id> not saved (...); orb left running` | Retry the pause, and check `cf-orbs status <orb>` |
| `orb was deleted at <time>` | Start a new thread |
| `image key <key> is not deployed` | Run `cf-orbs deploy` |
| `image <ref> is not registered` | Add the image to `images` in the config, then run `cf-orbs deploy` |
| `snapshots or orbs use image keys not in cf-orbs.config.jsonc: <keys>` (doctor) | Add the keys back to `images` with their `image/<key>.Dockerfile`, then run `cf-orbs deploy` |
| Amp's setup log shows `Repository configuration failed` | Amp reuses a cached project snapshot for 72 hours, even a bad one. Clear both caches (see below) |
| The first message after a long pause is slow | Either the disk restore is lazy, or the host doesn't have the image yet (40 to 50 s). `prewarm` helps |

### Repository configuration failed

Amp caches one project snapshot for each provider for 72 hours. After an image or setup change, new threads can still start from a disk made with the old image. To avoid that, clear both caches:

1. In Amp, delete the cached snapshot in Orb Settings → Snapshots, or run `amp projects snapshots delete <owner/repo> --resource <size>`.
2. In cf-orbs, run:

   ```sh
   npx cf-orbs snapshots forget --all-project
   ```

Do the same after a change to a repo's `.agents/setup`.

## Other messages

| You see | Cause and fix |
| --- | --- |
| `unknown command <name>` | Run `cf-orbs --help` |
| `unknown flag --<name>` | Run `cf-orbs --help` or `cf-orbs <command> --help` |
| `--<name> needs a value` | Pass `--<name> <value>` |
| `--lines must be 1-5000` | Pass `--lines 200` |
| `no orb id given` | Run `cf-orbs logs <orb id>` or `cf-orbs logs --provider`. `cf-orbs status` lists awake orbs only. For a paused orb, use `amp-<thread id>`, with the thread id from Amp (for example `amp-T-...`) |
| `invalid orb id` | Pass `amp-<thread id>` (for example `amp-T-...`). `cf-orbs status` shows awake orbs only |
| `no cf-orbs project in <dir>` | Run in the project directory, or pass `--dir <project dir>` |
| `forget --all-project would drop N mapping(s) and needs confirmation` | Run again with `--yes` |
| `--all and --older-than do not go together` | Use one of them |
| `bad --older-than <value>` | Use a number and a unit: `7d`, `36h`, or `90m` |
| `no snapshot deleted; wrangler failed on all N` | Check the lines above. Run `npx wrangler containers images list` |
| `<n> delete(s) failed` (uninstall) | Run `cf-orbs uninstall --yes` again. It skips what is deleted |
| `a token is in file(s) staged for the first commit` | Remove the token from those files or add them to `.gitignore`, then run `init --no-deploy` again |
| `a token is in tracked file(s)` (doctor) | Run `git rm --cached` on those files, or remove the token. Then make a new token, and purge the old one from history if you pushed |
| `Failed: <cause> — fix: rerun with CF_ORBS_DEBUG=1 and report the output` | An unexpected error. Run again with `CF_ORBS_DEBUG=1` and open an issue with the output |

## Provider log lines

Run `cf-orbs logs --provider` to see these.

| Line | Meaning |
| --- | --- |
| `Error: Amp rejected the orb provider token` | The secret is wrong or revoked. Set a new one: see [Rotate the token](/docs/guides/rotate-token/) |
| `Another amp orb provider is connected... Waiting for it to stop` | A second provider uses this token. Stop it |
| `amp orb provider exited with code <n>` | The provider restarts on its own. `entry.sh` waits 5 s, then backs off up to 5 min |

## Doctor output

A healthy install prints `All checks passed.` and exits 0. Each `FAIL` line holds its own fix. The full list of checks is in [Check health and read logs](/docs/guides/check-health/#doctor).

Worker logs, live:

```sh
npx wrangler tail --config .cf-orbs/wrangler.jsonc
```

If a problem remains, open an issue at [github.com/meirdick/cf-orbs](https://github.com/meirdick/cf-orbs/issues) with the `Failed:` line and the output of `cf-orbs doctor`. Remove tokens first.

Source: https://cf-orbs-site.mdick85.workers.dev/docs/troubleshooting/index.mdx