Your Next.js site runs perfectly on your own computer. Then you deploy it and the build fails, the page is blank, or something that worked an hour ago is suddenly broken. This is one of the most common problems in modern web development, and it almost always comes down to a handful of causes.
This guide walks through the ten most common reasons a Next.js app breaks on Vercel, in the order we usually check them. Work down the list. Most deployment problems are solved by the first four.
Start here: read the build log
Before you change anything, find the actual error. In Vercel, open your project, click Deployments, open the failed one, and read the Build Logs. The first red error is usually the real problem. The lines after it are often just fallout.
If the build succeeded but the live site misbehaves, check the Logs tab for runtime errors instead. Copy the exact error message. It will make everything below faster.
1. A missing environment variable
This is the number one cause. The .env file on your computer never goes to Vercel. Every variable your app needs has to be added in Project Settings → Environment Variables, and you choose which environments get it (Production, Preview, Development).
Two things trip people up. First, variables only apply to new deployments, so you have to redeploy after adding or changing one. Second, a variable that the browser needs must start with NEXT_PUBLIC_, and it is baked in at build time. Never put that prefix on a secret like an API key or a database service key, because it makes the value public.
2. TypeScript errors your editor ignored
The development server will happily run with type errors. next build will not. If the log says "Type error," run npx tsc --noEmit on your computer to see every one of them at once, then fix them. Turning type checking off to get a green build only hides real bugs and moves the failure to your visitors.
3. File names with the wrong capital letters
macOS and Windows treat Header.tsx and header.tsx as the same file. Vercel runs Linux, where they are different. The result is a "Module not found" error for an import that works locally. Make every import path match the file name exactly, capitals included. If you rename a file's capitalization, use git mv, because Git on a case-insensitive system may not notice the change.
4. Lockfile and Node version mismatches
If the install step fails with a message that package.json and package-lock.json are out of sync, run npm install locally and commit the updated lockfile. Also check Project Settings → General → Node.js Version. It should match the version you develop on, and you can pin it with an engines field in package.json.
5. Hydration errors
Messages like "Hydration failed" or "Text content does not match server-rendered HTML" mean the HTML the server produced is different from what the browser rendered first. The usual causes are using Date.now(), Math.random(), window, or localStorage while rendering, invalid HTML nesting such as a div inside a p, or a browser extension changing the page.
Move browser-only logic into useEffect so the first render matches on both sides, and fix any invalid nesting. For a difference you truly cannot avoid, like a timestamp, you can add suppressHydrationWarning to that one element.
6. Server and Client Components mixed up
In the App Router, components are Server Components by default. If one uses useState, useEffect, or an onClick handler, you will get an error telling you to mark it as a client component. Add 'use client' to the top of that file, and only that file. Going the other way, do not import code that uses secrets or talks to your database into a client component.
7. A page that shows old or wrong content
Next.js caches heavily. A page generated at build time stays as it was until something tells it to update. If your content changes in a database or CMS but the site does not, you need a refresh strategy: time-based revalidation, on-demand revalidation after an edit, or rendering the page on each request. Caching defaults have changed between Next.js versions, so check the documentation for the version you run.
8. A 404 on a page that works locally
For dynamic routes like [slug], check that the folder structure is correct, that page.tsx sits inside the folder named for the route, and how generateStaticParams handles slugs it does not know about. Also look for redirect or middleware rules that behave differently in production, and for the capitalization problem from number 3.
9. Images that will not load
The Next.js image component only optimizes images from hosts you have allowed in next.config under images.remotePatterns. If you see a "hostname is not configured" error, add that host there, as specifically as you can. Very large original images also slow pages down, so resize them before uploading.
10. Functions that time out or run out of database connections
API routes and server actions run as serverless functions. They have time limits that depend on your Vercel plan, and each one can open its own database connection. The symptoms are a site that works for a while and then throws 500 errors, "too many connections," or timeouts. Use your database provider's pooled connection string, keep slow work out of the request, and raise the function duration setting if your plan allows it.
Built with an AI tool? Check these too
Apps generated by AI coding tools hit the same problems, plus a few of their own: placeholder environment variables that were never filled in, packages that are imported but not installed, hard-coded localhost addresses, and secret keys left in code that runs in the browser. If your app was built that way and you are stuck on the last stretch, our AI App Help service is built for exactly that.
Still stuck on a failed deploy?
Send us the build log and a link to your repository. We will tell you what is wrong and what it will take to fix it.
Common questions
Q: Why does it work locally but not on Vercel?
Your computer and Vercel are different environments. The usual differences are environment variables, file name capitalization, the Node version, and a production build that is stricter than the development server.
Q: Should I turn off type checking to get the build through?
No. It makes the build pass but leaves the bugs in place. Fix the errors instead. Most take only minutes once you can see them with npx tsc --noEmit.
Q: My site is down right now. How do I get it back quickly?
In the Deployments tab you can usually go back to an earlier successful deployment while you debug. The options depend on your plan. That buys you time to fix the problem properly.