Deployment Troubleshooting

Start from the failing execution surface. A local build, a Vercel deployment, a provider webhook, and a scheduled job each use different configuration and produce different evidence.

The wrong Vercel project is linked

Stop before deploying. Inspect .vercel/project.json, confirm the project and team, and rerun the pinned vercel link flow if either is wrong. Do not copy another application's .vercel/ directory into this checkout.

Production uses local or stale environment values

The baseline deployment wrapper reads .env.production.local, not the values you most recently edited in .env.local.

npx --yes vercel@54.21.1 env pull .env.production.local --environment=production
npm run deploy:vercel

Pull again after every Vercel environment change. Public NEXT_PUBLIC_* values are embedded into the client build, so changing them requires a new deployment.

Preflight rejects the site URL

NEXT_PUBLIC_SITE_URL must be a valid HTTP or HTTPS URL and must not point to localhost, 127.0.0.1, or ::1. In production, keep BETTER_AUTH_URL, NEXT_PUBLIC_SITE_URL, and NEXT_PUBLIC_APP_URL aligned to the intended origin unless you intentionally operate separate origins.

Preflight passes, but another gate fails

This is possible and expected. Preflight checks capability configuration, database reachability, selected migration blockers, and TypeScript. It does not run lint, unit tests, integration tests, or a production build. Run the failing command directly and fix that result rather than treating preflight as proof of the full repository.

db:push fails

This is the intended behavior. The starter disables schema push. Generate, review, and run migrations:

npm run db:generate
npm run db:migrate

Do not invoke drizzle-kit push directly.

Database connection fails

• Confirm DATABASE_URL points to the intended database and contains required TLS parameters.
• Confirm the database accepts connections from your current network or Vercel region.
• Check connection-pool limits and provider maintenance status.
• Test with npm run preflight; it uses a ten-second connection timeout and a simple query.
• Never paste the connection URL into an issue or chat transcript.

Migration safety reports duplicates

Preflight checks duplicate subscription users, credit transaction sources, and webhook provider event IDs because committed unique indexes depend on those invariants. Inspect and reconcile the reported rows before migration. Do not delete records blindly or manually mark the migration as applied.

A migration ran locally but not in production

The production runner applies only committed drizzle/*.sql files that are absent from the target database's app_migrations table. Confirm that:

• the SQL file is committed and included in the deployed revision;
• the deployment uses the intended DATABASE_URL;
• the filename was not reused or edited after an earlier application;
• another migration process is not running concurrently.

Authentication fails only in production

• Production must enable at least one complete auth method: email/password or Google OAuth.
• Email/password requires NEXT_PUBLIC_ENABLE_EMAIL_AUTH=true and working email delivery.
• The supported Vercel baseline requires Resend and a verified RESEND_FROM_EMAIL domain.
• Google OAuth requires both server credentials; One Tap additionally requires NEXT_PUBLIC_GOOGLE_CLIENT_ID.
• Confirm the provider callback origin matches BETTER_AUTH_URL.
• Secure cookies require HTTPS in production.

Verification or password-reset email does not arrive

Check the Resend delivery log, sender-domain verification, recipient status, and Vercel function log. If using SMTP outside the baseline path, all SMTP host, port, user, password, and from-address values must be complete. Remove credentials and message links before sharing diagnostics.

The baseline deploy rejects enabled payments

npm run deploy:vercel intentionally requires NEXT_PUBLIC_ENABLE_PAYMENTS=false. It is the verified core baseline, not a generic optional-capability deploy wrapper. See Deploy to Vercel and do not hide the flag to bypass the check.

Payment preflight reports a missing catalog

When payments are enabled, preflight requires the selected provider's credentials, webhook secret, and every built-in visible Starter/Pro monthly and annual plan plus the small, medium, and large credit packs. If your product exposes a smaller catalog, update the product catalog and its readiness contract together; do not leave the UI pointing at unconfigured identifiers.

Keep keys, prices/products, webhook secrets, and endpoints in the same test or live mode.

Webhook returns 400

The signature is missing or invalid. Confirm:

• the provider sends to /api/payments/webhook;
• PAYMENTS_PROVIDER matches the sender;
• the signing secret belongs to this exact endpoint and environment;
• no proxy or handler transformed the raw request body.

Webhook returns 503

The selected provider is incomplete. Run preflight in the same target environment and supply every reported variable. Credentials for the inactive provider do not make the active provider ready.

Webhook returns 500

Signature verification succeeded, but application processing failed. Inspect the application error, correct the database or domain failure, then replay the original provider event. The webhook inbox releases failed work when possible and can reclaim an expired unprocessed lease.

A replay returns deduped: true

The delivery was already processed or another attempt currently owns it. Check webhook_inbox and the affected business tables before replaying again. Repeated redirects or repeated webhook sends are not a substitute for database read-back.

Cron returns 401, 503, or 500

A successful run with zero grants is normal when no subscription boundary is due. The job runs daily but grants on monthly subscription boundaries.

Storage or AI capability fails preflight

Object storage requires a supported provider (r2, s3, or minio), endpoint, access key, secret key, and bucket as one complete set. AI image generation requires an enabled feature flag and a configured Fal, ModelScope, or DashScope provider. Disable an unfinished capability instead of deploying partial credentials.

Rate limiting behaves differently across deployments

The included limiter stores counters in one process. It is useful for local behavior and basic request shaping, but it is not a production-safe distributed limiter for Vercel, multiple instances, or load-balanced deployments. Replace it with a shared serverless-compatible store before relying on limits for abuse prevention.

For command and environment details, see Commands and Environment.