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. Two things are generated from the code itself, and they are the ones to check a page against: for the CLI, pithy schema --json describes the installed version from the binary; for the routes, pithy contract writes each Worker’s OpenAPI document from the app it composes. 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
File it on the Bug report form at github.com/pithy-sh/pithy. It asks for what a maintainer needs to reproduce it: the version, your OS and shell, the command and its output. An idea goes on the Feature request form beside it.
Building with the Claude Code plugin? /report-kit-gap does this for you: it searches first, fills the form, leaves your code and secrets out, and files only on your yes.
A vulnerability is never an issue. Report it privately, at github.com/pithy-sh/pithy/security/advisories/new. A public report is readable by everyone running an unpatched Worker before a fix exists.
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.