When something breaks

Nothing in this project fails quietly. When a step refuses to run it says why, and it gives the reason a short code — E_PLACEHOLDER_ID, E_MISSING_SECRETS — so you can look it up instead of guessing.

Start here

Run this in your project:

pnpm support

It prints one report of what your project looks like right now: which resources were never created, which secrets are missing, which database changes have not been applied, how far behind the starter you are. It reads no secret values, so the report is safe to show anyone.

Then hand it to your assistant:

Read this report and fix what it names.

Most of what it finds can be put right without anyone else being involved. If something still fails, find its code below.

Nothing has been set up yet

E_NOT_SHIPKIT

What it means. The command was run somewhere that is not one of these projects.

Why it happened. Almost always the wrong folder — a terminal opened in your home directory rather than in the project.

What to do. Move into the project folder (the one with shipkit.json in it) and run the command again. If you are not sure where it is, ask your assistant: "Which folder is my project in? Take me there."

E_PLACEHOLDER_ID

What it means. The project is still holding a TODO- where the name of a real database or storage bucket should be.

Why it happened. The project ships with deliberate blanks so it cannot accidentally deploy into the wrong account. Those blanks are filled in by the provisioning step, and that step has not run yet for this environment.

What to do. Provision that environment — staging first, then production. Ask your assistant: "Provision the staging environment for this project." You have to be signed in to Cloudflare for this to work.

E_NOT_LOGGED_IN

What it means. Cloudflare does not know who you are.

Why it happened. You have not signed in yet on this computer, or the sign-in has expired.

What to do. Run pnpm exec wrangler login. A browser window opens, you approve it, and you are done. If you are working somewhere without a browser, a Cloudflare API token in CLOUDFLARE_API_TOKEN does the same job.

E_STALE_ID

What it means. The project is pointing at a database that does not exist in the Cloudflare account you are signed in to.

Why it happened. Usually two accounts — a personal one and a work one — and you are signed in to the wrong one. Occasionally it means the database was deleted from the Cloudflare dashboard.

What to do. Check who you are with pnpm exec wrangler whoami. If it is the wrong account, sign in again as the right one. If the database really is gone, provision that environment again.

Deploying and going live

E_PENDING_MIGRATIONS

What it means. Your database structure has changes that have been written but not applied.

Why it happened. Something added a column or a table, and the step that tells the live database about it has not run.

What to do. Apply them to that environment before deploying. Deploying code that expects a column the database does not have is how a site starts returning errors to real people. Ask your assistant: "Apply the pending database changes to staging."

E_MISSING_SECRETS

What it means. The deployed site needs a value — a signing key, an API key — that was never given to it.

Why it happened. Secrets live on your computer in .dev.vars for local work, and have to be set separately on each deployed environment. That second half is easy to miss.

What to do. Set them on that environment. Put the values in .dev.vars.staging or .dev.vars.production (both are ignored by git and never leave your machine) and run the secrets step. Never type a secret value into a chat with your assistant.

E_WORKER_NOT_DEPLOYED

What it means. You are trying to configure a site that does not exist yet.

Why it happened. Secrets can only be attached to something that is already running, so the very first deploy has to come first.

What to do. Deploy that environment once, then set the secrets, then deploy again. The first deploy may briefly fail for want of the secrets; that is expected and the second one fixes it.

E_PRODUCTION_GATE

What it means. Nothing went wrong. Something asked to touch production and was refused because nobody said it could.

Why it happened. Every command that can affect the live site your customers see requires explicit confirmation, every time. There is no way to turn this off, and that is the point.

What to do. If you did mean it, say so and run it again with the confirmation. If you did not mean it, you have just been saved a bad afternoon.

Commands that stopped

E_CMD_FAILED

What it means. A tool underneath — usually wrangler, the build, or the tests — exited with an error. The real reason is in the output just above.

What to do. Read the last twenty lines before this one; the actual complaint is in there. If it is not obvious, save the output to a file and attach it:

pnpm support --last-error <the file>

E_VERIFY_FAILED

What it means. The step ran, then checked its own work, and the check failed.

Why it happened. Something was applied but did not take effect — a migration that still shows as pending afterwards, for instance.

What to do. This one is worth reporting. Run pnpm support and send the report.

E_TOOL_DRIFT

What it means. An external tool changed underneath the starter and no longer behaves the way it did.

Why it happened. Not your doing. Something upstream released a new version with different output.

What to do. Report it. This is exactly the kind of thing that gets fixed in the starter for everybody at once.

E_JSONC_AMBIGUOUS

What it means. wrangler.jsonc — the file describing your three environments — has been edited into a shape the tooling cannot safely change.

Why it happened. A hand edit, or a merge that was resolved the wrong way.

What to do. Ask your assistant: "Compare my wrangler.jsonc against the starter's and tell me what is different." The three-environment layout has to survive; the values inside it are yours.

E_USAGE, E_PRECONDITION, E_NONINTERACTIVE, E_DECLINED

These four are not really failures.

• E_USAGE — the command was given something it did not understand. The correct form is printed with it.
• E_PRECONDITION — something has to happen first, and the message says what.
• E_NONINTERACTIVE — a question needed answering and there was nobody to ask. Run it yourself in a terminal, or pass the answer as an option.
• E_DECLINED — you were asked, and you said no.

Still stuck

Read how to reach us. Include the output of pnpm support, what you were trying to do, and what happened instead.