Deployment

Deployment builds the app, applies remote database migrations, and uploads the Worker in order. Check which stage failed before changing provider configuration or retrying the release.

Find the failing stage

The deployment guide covers initial production setup. Use your own resources throughout the Wrangler configuration.

The app shows old settings

Vite embeds public values during the build. If the deployed UI still shows a local URL or old product name, supply the production build values and rebuild.

Keep the auth origin aligned with the actual domain. Changing runtime secrets alone does not replace compiled browser settings. See environment configuration.

A pull request has no preview

Check that Cloudflare's GitHub App can access the repository and that preview builds are enabled for the branch. Inspect the build result and Preview command in Cloudflare. A successful GitHub Actions check alone does not confirm that a preview was published.

If the preview loads but sign-in or data access fails, check its variables, secrets, bindings, and callback URLs. See GitHub deployment setup.

Add missing production secrets

Local secret files are not deployed to the Worker. Store each required production secret on the intended Worker:

pnpm exec wrangler secret put VARIABLE_NAME

Use the names from the environment schema and add credentials for every social provider you enable. Check account permissions if resource access fails.

Fix sign-in redirects

Match the auth origin, public URL, and provider callback. Keep local and production callbacks separate where required, and use real Turnstile keys configured for the deployed hostname.

The OAuth guide lists the required callbacks.

Checkout succeeds but access stays Free

If checkout succeeds but access stays Free, inspect webhook delivery, the signing secret, and the app's subscription record. Prices, credentials, and the endpoint need the same Stripe account and mode.

A browser redirect does not update the subscription by itself. Local forwarding uses the Stripe CLI listener's secret; production uses the endpoint's own secret. See subscriptions.

Email does not arrive

Confirm your sending domain is verified and the sender address is allowed. Test direct verification mail separately from the delayed welcome job.

The welcome job rechecks the customer before sending and retries processing failures. Email sending and background jobs cover these paths.

AI responses fail

Check the configured model, gateway, provider access or funded billing, and AI binding. Worker and gateway logs should identify an access or inference failure.

Use the AI guide for setup and the model recipe for a different configuration.

A package fails in the Worker

The kit enables Node compatibility, but Workers remains a different runtime from a long-running Node server. Some APIs have partial support or runtime-specific behavior.

A virtual filesystem is available at the project's compatibility settings. Use R2 for durable files and D1 for application records rather than expecting a persistent local disk.

Check the package's actual operations against Node compatibility and Workers filesystem behavior, then test them on the Worker runtime.

Reduce the upload size

Compare the compressed upload with your Worker plan's limit. Review large dependencies, whole-library imports, and embedded assets.

Keep server-only dependencies behind the server boundary and preserve validation and authorization when reducing the bundle.

The status check passes but a feature fails

A status response confirms the Worker can serve that endpoint. Check the integration that is failing separately, using observability and the deployment checklist.