pithy doctorThe first command to run when your model of the project and the project disagree. It writes nothing.
The rule it follows
pithy doctor is the command, exit codes is what a finding does to the exit, and reading your logs is where to go when the project is fine and the runtime is not.
Knowing this stops you fighting the report.
A finding fails the exit. A contradiction between your own config and your own wiring.
A step not yet taken passes. No domain yet, an environment not provisioned, a secret registry never provisioned. Every project is in those states on day one, and turning the report red for everyone on day one teaches people to ignore it.
A check that could not run gates nothing and says so — reported as skipped with the reason, never rendered as a pass. A check nobody ran established nothing.
Under --json, every failure names its remedy. failures lists each check that fails the exit, and each entry carries fix: a pithy command you can run as written, or null when the remedy is an edit or a step only a person may take. The findings in each block carry fix too, on the same rule, with a few stated exceptions in pithy doctor.
The findings, and what each one means
bindings
A required binding is missing from a stanza — and it checks both halves. A Durable Object needs its config entry and an export from your Worker’s entry module, and wrangler refuses the deploy when the second is missing.
Remedy: the command doctor names on the line. A missing D1, KV, R2 or queue binding is written by pithy worker sync --worker <worker>, with --env <env> when only deployed environments lack it: run pithy worker sync --worker api --env staging. Every other kind, a Durable Object’s entry and its export included, is written by pithy upgrade --worker <worker>.
migrations
Asked in both directions, and the second is why the line exists.
N pending means run migrate. A migration the database has applied that you no longer declare is a different fault with a different remedy — and invisible to a pending count.
dev: not set up is neither. The checkout has no local D1 store yet, as on a fresh clone or a CI runner, so nothing is read and nothing fails the exit. pithy setup creates and migrates it. A store that exists and is behind is N pending, and does fail.
Remedy: on dev, delete local state and re-run; on a deployed environment, restore the migration or remove its ledger row deliberately.
prereqs
A capability composed without its peers. The Worker will not start at all — this is caught before you find out the hard way.
Remedy: compose the missing peer into that Worker. Doctor names each one as a command that runs as written — pithy add secrets --worker api, or pithy add email --worker api --with-prerequisites for a peer that brings prerequisites of its own. A peer with an option that has no default, such as payments’ billingSubject, is named once per value it takes, and carries no fix: which value is yours to choose.
entitlements
Routes gating on an entitlement while nothing composed provides one. The Worker is not broken — it is silently paywalled shut, and the runtime cannot tell that from a legitimately unentitled user.
Remedy: compose a provider, or remove the gates. Report-only, because which is right is your decision.
workflows
The one whose entire symptom is that nothing happens.
A job declared and never synced ships with no binding and no cron trigger. No request fails, no log line appears, no probe goes red — the cron simply never fires.
Remedy: pithy worker sync.
origins
Three shapes: no origin at all (legitimate on day one, reported but not failing), an origin nothing routes, and the public subdomain left open beside a custom domain — where the same-origin gate then refuses exactly the requests that establish who somebody is.
The last two fail.
Project name:
Two states fail, and neither ever advises deleting anything.
Drifted — every declared name leads with one and the same other project and yours appears nowhere. The only shape a one-string rename can leave.
Orphaned — a database’s owner stamp proves Pithy created it under another project’s name.
A single foreign name, a mix, an unset name and an unreadable config all pass: none of them establishes anything, and <app>-<env>-<resource> is also the ordinary Cloudflare convention. A database you brought with you is not an orphan.
Cloudflare:
Configured and broken fails. Absent does not — a project that has not been provisioned yet is legitimate.
It names the file it resolved and where the credentials came from — the file, the environment, or a sign-in bound to this directory. That distinction matters: CI has no file and authenticates from variables, so a report naming a path with nothing at it was misleading about the thing you were about to go and check. It also says whether an audit row can name a person: a sign-in names who signed in, an account token only its own name.
A pinned account the credentials do not match fails, names both, and is decided before anything reaches the network.
A profile bound here that is signed out, expired, or contradicted by an exported credential fails too, because every command run here refuses on the same fault. Remedy: pithy cloudflare connect, or unset the exported pair — the line says which.
Settings:
The one tier that looks at a value rather than at presence. A sending address on a domain nobody onboarded, a base URL nothing serves.
Local findings fail. Account findings fail too — but only when the account was reached.
Support search:
Support’s full-text index is kept current by database triggers, which pithy support provision creates. A deployed index with no triggers, or only some of them, fails — messages are stored and readable, and quietly missing from search. So does search.fts on with no index provisioned: it is on by default, so every project that upgraded support and has not re-provisioned is in this state, searching through the LIKE fallback.
Remedy: pithy support provision --worker <worker>. It creates the triggers and indexes the messages written while none existed. Run it after upgrading support.
A read that could not happen is said out loud — offline, or no credentials — and gates nothing.
Worker vars:
env.<name>.vars replaces the top-level block rather than merging with it. A var the top level sets and a stanza leaves out deploys without it, silently.
A declared var fails the exit — one your pithy.config.ts or a capability declares with defineVars. Missing from a stanza, held at the top level’s value where the declaration gives that environment its own, or set to a value its schema refuses: the Worker’s own config says what the stanza must hold, and the deploy would run something else.
An undeclared var a stanza drops only reports. Nothing says what its value should be in that environment, so the line names the one to add and leaves the choice to you.
Remedy: pithy worker sync --worker <worker> writes every declared var a stanza lacks and rewrites one held at the top level’s value. A refused value is yours, and sync keeps it — set one the schema takes in wrangler.jsonc by hand. In --json the block is varStanzas; Worker vars: has each line’s shape.
Capabilities declared twice:
A capability the project root declares in its dependencies beside a Worker that declares it too. A Worker declares what it composes in its own package.json, which is where pithy add installs it. The root has no Worker, so its copy is a second declaration that drifts from the first.
Reports only. Both declarations install and resolve, so the drift has not happened yet. A root devDependency is never counted.
Remedy: take it out of the root package.json’s dependencies. No command makes that edit, so fix is null. In --json the block is duplicateCapabilities; see Capabilities declared twice:.
Root imports:
A package the root vitest.workers.config.ts imports that the project root cannot resolve. The config loads from the root, and under a package manager that does not hoist, the root resolves only what its own package.json declares. A package only a Worker declares fails the Workers tests with ERR_MODULE_NOT_FOUND after a clean install. Resolution stops at the project root, so a feature worktree cannot pass on the main checkout’s node_modules.
Reports only. Where the install hoists, the import resolves and the tests pass. Where it does not, those tests fail on their own.
Remedy: declare the package as a root devDependency — the line names it, at the range a workspace member declares — then run your package manager’s install at the root. pithy add declares it for you when a test binding it writes imports one. A package the root already declares and has not installed needs only the install. fix is null. In --json the block is rootImports; see Root imports:.
Workers tests:
A composed capability’s test bindings missing from the root vitest.workers.config.ts. The first request through a Worker’s fetch checks every binding its composition requires, so a Workers test that sends one fails on a binding the config does not state.
pithy add writes them. This names a project that added the capability before it did, removed a line by hand, or changed a Worker’s config so an optional binding became required. One line per capability, naming the Workers that compose it. A binding no test config can provide on its own, such as a Durable Object or a Workflow, is never named, and a project with no vitest.workers.config.ts hears nothing.
Reports only. A project may test its Workers some other way.
Remedy: run pithy add <capability> --worker <worker> again — on a Worker that already composes it, the re-run writes the test bindings. Or add them by hand. In --json the block is testBindings, and each entry’s fix is that command, or null when no single command is. See Workers tests:.
The locations block, which is not a finding
Config dir:, Secrets:, Ports:, Dev login:.
Every line reports a location, and each is a path nothing in your repository mentions. Only one can fail the exit: Dev login:, when dev.json will not parse or names no user. No file at all is not a fault.
The one line there you can act on is a ports row marked not on disk: pruning cannot tell a deleted checkout from a moved one, so that row means you renamed that directory.
Working offline
pithy doctor --offlineNo ambient credentials, no network call. The variable form says the same thing to every command and is inherited by anything spawned.
Setting the config directory does not imply it — that conflates read config from here with do not use the environment, and CI legitimately means the first without the second. Set both and nothing in the CLI has a credential to authenticate with.
When doctor is clean and it is still broken
Then it is a runtime problem rather than a wiring one. Filter your logs by version, then by request id.
And check the one thing doctor structurally cannot see: a route the SPA shell is answering instead of your Worker.
pithy ui sync --check --worker apiNo test suite sees that either, because tests call handlers directly and the asset router is never in the picture.