Deployment troubleshooting

Most deployment issues fall into one of three buckets.

1. Missing environment variables

The build itself runs without env vars, but runtime routes will 500 the moment they try to read process.env.X and find it undefined.

• On Vercel, set every variable in Settings → Environment Variables for the Production, Preview, and Development environments.

• Trigger a redeploy after adding env vars — they don't take effect on existing deployments.

2. Image domains not allowed

Next.js will refuse to render an image from a domain not listed in next.config.mjs. Add your CDN:

images: {

  remotePatterns: [

    { protocol: "https", hostname: "cdn.example.com" },

    { protocol: "https", hostname: "*.r2.cloudflarestorage.com" },

  ],

}

3. Prisma client not generated

If you see "Cannot find module '.prisma/client'" or "Schema parse error" on Vercel, add a postinstall script:

"scripts": {

  "postinstall": "prisma generate"

}

Other common issues

• Build memory limit — disable the experimental fontLoaders if you don't use them, and make sure you're on Vercel's standard or higher tier.

• Custom domain not propagating — DNS can take up to 24 hours; use a service like dig +short yourdomain.com to verify.

• HTTPS redirect loops — check your reverse proxy or CDN isn't double-wrapping the request.