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:
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 |
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 |
<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), 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:
-
In Amp, delete the cached snapshot in Orb Settings → Snapshots, or run
amp projects snapshots delete <owner/repo> --resource <size>. -
In cf-orbs, run:
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 |
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.
Worker logs, live:
npx wrangler tail --config .cf-orbs/wrangler.jsoncIf a problem remains, open an issue at github.com/meirdick/cf-orbs with the Failed: line and the output of cf-orbs doctor. Remove tokens first.