Troubleshooting

When something goes wrong, identify which step did not complete before deciding what to change. This chapter contains six articles organized around the current default template's workflows. Problems in the same workflow are covered together, so you do not have to keep switching between authentication, email, and OAuth, or between payments and webhooks.

Find an article by symptom

1. Establish reproducible conditions

Record the environment, code version, URL, time of the operation, and shortest steps to reproduce the issue. For example, “In production, a regular account purchased the yearly plan. Stripe shows the payment as complete, but the product is still unavailable after refreshing the product page” is easier to investigate than “Payments are broken.”

Inspect local and production environments separately. Missing records in local D1 do not show whether a production payment was saved. Likewise, changing local .env does not let you test that change in production.

An API's code may be a numeric result code, part of a third-party protocol, or absent altogether. Look up numeric codes in src/errors.ts. Do not assume every response is a complete APIResponse<T>.

Redact cookies, tokens, secrets, verification codes, and recipient information before sharing troubleshooting details. Local email previews include message bodies, so check terminal output before copying it as well.

2. Check diagnostics, then verify the workflow

From the root of the initialized project, choose the check for your environment:

# Local configuration
npm run doctor

# Production configuration and Cloudflare account access
npm run doctor:remote

doctor checks configuration, variables, binding names, database directories, and related settings. doctor:remote reads .env.production and also checks that remote resource IDs are filled in and that the current identity can access the configured account.

These commands do not fully test your production services. Passing the checks does not prove that every resource exists, that Resend delivered an email, that Stripe completed a callback, or that a Queue task ran. Disabled optional services may produce notices or warnings. Evaluate them in the context of the feature you are testing.

3. Continue from the last successful step

A typical payment flow is:

Create Checkout → The user pays → Verify the webhook signature
→ Update payment records → Create a business Event → Execute Commands → Grant user access

If the correct payment event has arrived, inspect payment records and access processing next. There is no need to keep changing the Checkout page. If no callback has arrived, address the callback URL, secret, and delivery issues first.

The same applies to background jobs. Completion of queue.send(), message acknowledgment, Command success, and completion by an external service are separate stages. Verify each one separately.

4. Verify the fix

Repeat the same reproduction case and check related failure scenarios. For example, after correcting a plan mapping, check both that a new payment grants access and that duplicate callbacks do not create duplicate grants.

After code changes, run the project's npm run verify. After changing configuration or provider settings, also test the relevant workflow. Successful compilation does not prove that an external service is available.

Common errors

For exact field definitions, see the reference. To complete a release from the beginning, see deployment.