Start with doctor
pithy doctor is the command; diagnosing a broken project is the longer path when it does not say enough; error codes decode what it prints; and reading your logs is where a runtime problem shows up instead.
pithy doctorIt reports what a deploy would fail on, and names the command that fixes each one — a binding missing from wrangler.jsonc, pending migrations, a declared route nothing serves, a gated route with no entitlement provider.
A step you have not taken yet passes. A project with no domain and nothing provisioned is not red on day one, because turning the report red for everybody on day one teaches people to ignore it.
It also prints every path — your config directory, your secrets file, the port registry — so you never have to remember them.
The three failures people hit most
A binding without its class-migration tag. A Durable Object binding is one entry; the tag is another, in a different block, repeated per environment. Without it you deploy a Worker whose class does not exist.
A declared route that was never synced. A domains block added by hand declares an address nothing serves — run pithy worker sync. The same applies to a declared Workflow and its cron.
A capability composed but not provisioned. add writes bindings and touches no account; provision stands up what those bindings point at.
Read the error’s code, not just its message
domain/reason, and the code is stable where the message is not.
The detail you see in your logs is stripped before it reaches a client — so an operator’s diagnostic and a caller’s message are deliberately different things.
401 and 403 are the pair worth separating. A client that treats them the same refreshes a perfectly good token forever.
Read your logs with the run attached
c.var.log carries request correlation already. In a Workflow, build one and bind the run context, or a failure is a line with no way back to which instance produced it.
Never wire the logger to a client surface — it carries error detail, which is the inverse of what the HTTP codec does.
When the docs and the code disagree
The code is right.
These pages are hand-written and there is no generated reference — no OpenAPI document, no error catalog. Where a page here is wrong, that is worth reporting.
When a build is stale
rm -rf .build. A stale artifact with a newer mtime has caused this more than once.
Reporting something
Say which command, which environment, and what the --json output was. Every command emits one, and it carries more than the human-readable line.
Include the error code. It is the one part of the payload that is stable.
Do not paste a secret. No command prints one — and if you found something that does, that is the bug worth reporting first.