Deploy errors

For errors while npm run setup deploys, also see Setup errors → Deploy.

Missing environment variable …Copy Anchor Link

Missing environment variable DODO_PAYMENTS_API_KEY. Run the setup script or copy .env.example to .env.local and fill it in.

Why: the app needs a variable that isn't set where it runs.

Fix:

• Live site: add it in Vercel, Settings → Environment Variables, for the Production environment. Then redeploy: changes only apply to new deployments.
• Preview deployments (from branches) use the Preview environment, which setup doesn't fill in. Add the variables there too if you use previews.
• Locally: add it to .env.local and restart npm run dev.

See Environment variables for which ones are required.

I changed a variable but nothing changedCopy Anchor Link

Why: Vercel reads environment variables when it builds. Existing deployments keep the old values.

Fix: Deployments → ⋯ on the latest → Redeploy. Locally, restart npm run dev.

The build fails on VercelCopy Anchor Link

Fix: run npm run build on your computer. It nearly always fails the same way, with a clearer message. See Build errors. The full Vercel log is under Deployments → the failed deployment → Build Logs.

npm error engine / Node version errorsCopy Anchor Link

Why: Vercel is building with an older Node.js.

Fix: Settings → Build and Deployment → Node.js Version → the newest available (22.x or later).

Works locally, fails on Vercel with Module not found for a file you haveCopy Anchor Link

Why: file name capitalisation. macOS and Windows ignore it; Vercel (Linux) doesn't. import Hero from './hero' fails if the file is Hero.tsx.

Fix: match the import's capitalisation to the file name exactly. To rename a file's case in Git: git mv hero.tsx Hero.tsx.

The live site shows an error pageCopy Anchor Link

Open Vercel Logs (or Observability → Errors) and find the request. The message is usually one of:

Pages are slowCopy Anchor Link

Why: server functions far from the database. Vercel's default region is Washington, D.C.

Fix: check vercel.json has "regions": ["<region next to your database>"] and is committed. See Function region. Then redeploy.

Custom domain shows "Invalid Configuration"Copy Anchor Link

Why: your domain's DNS doesn't point to Vercel yet.

Fix: in Vercel, Settings → Domains, the domain shows the exact records to add at your registrar. Remove old A or CNAME records for the same name that point elsewhere. DNS changes can take up to 48 hours, usually much less.

Share previews and the sitemap show localhostCopy Anchor Link

Why: NEXT_PUBLIC_APP_URL in Vercel is wrong. Setup sets it when it deploys; it may have been overwritten.

Fix: set it to your real address, such as https://yourdomain.com, and redeploy. Share previews on social sites are cached: use their debug tools (such as LinkedIn's Post Inspector) to refresh them.

Deploys don't happen when I pushCopy Anchor Link

Why: setup deploys from your computer; it doesn't connect Git.

Fix: Project → Settings → Git → Connect Git Repository in Vercel. From then on, every push to main deploys.

vercel.json disappeared or has no regionsCopy Anchor Link

Why: it wasn't committed, so deploys from Git don't have it.

Fix: run setup with deploy again, or add it by hand, then commit:

{
  "regions": ["sin1"]
}