Common Next.js Deployment Errors on Vercel (and How to Fix Them)

Your Next.js app runs perfectly on localhost:3000, then breaks the moment you push to Vercel. It's one of the most common — and most confusing — moments in App Router development. Here are six errors that show up again and again, why they happen, and the exact fix for each.

What it looks like: the deploy fails during "Installing dependencies" or "Building," even though npm run build works fine on your machine. The log usually shows a dependency resolution error or a syntax error in a file that "shouldn't" be affected.

npm ERR! code ERESOLVE
npm ERR! Unable to resolve dependency tree
Error: Command "npm run build" exited with 1

Why it happens: Vercel installs dependencies fresh, using your lockfile, on whatever Node version is set in your project settings. If your local Node version differs from Vercel's, or your lockfile is out of sync with package.json, the install resolves differently — and packages that "just worked" locally suddenly don't.

The fix: pin your Node version and make sure the lockfile is current.

// package.json
{
  "engines": {
    "node": "20.x"
  }
}

Delete node_modules and your lockfile locally, run npm install again, and commit the fresh lockfile. In Vercel, double-check the Node version under Project Settings → General.

What it looks like: the build fails only on Vercel, pointing at an import that works fine on your laptop.

Module not found: Can't resolve './Components/button'
Import trace: ./app/page.tsx

Why it happens: macOS and Windows file systems are case-insensitive by default, so Button.tsx and button.tsx look identical to your editor. Vercel builds on Linux, which is case-sensitive — so an import path that doesn't match the file's exact casing fails there, and only there.

The fix: match the import to the file's exact casing.

// Before
import Button from './Components/button'
// After — matches the real filename exactly
import Button from './components/Button'

If you're not sure where the mismatch is, search your imports for the folder or file name and compare it letter-by-letter against your actual file tree.

What it looks like: a feature that reads an env var works locally but the value is undefined once deployed — often a broken API call or a feature flag that's silently always off.

console.log(process.env.NEXT_PUBLIC_API_URL)
// undefined — in the browser, on the live site

Why it happens: two rules trip people up here. Any env var read in browser-side code must be prefixed with NEXT_PUBLIC_, or it gets stripped out at build time. And Vercel never reads your local .env.local file — every variable has to be added manually in the dashboard, per environment.

The fix: rename the variable if it's used client-side, then add it in Vercel: Project → Settings → Environment Variables → add the key and value → select Production/Preview/Development → redeploy.

What it looks like: a broken image icon, or a thrown error naming a hostname that "isn't configured."

Error: Invalid src prop (https://cdn.example.com/photo.jpg) on `next/image`,
hostname "cdn.example.com" is not configured under images in your `next.config.js`

Why it happens: next/image optimizes and proxies external images, but only from domains you've explicitly allowed. A plain <img> tag would just work, which is why this one catches people off guard the first time.

The fix: allow-list the domain.

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'cdn.example.com' },
    ],
  },
}

Redeploy after saving — config changes don't apply to a deployment that's already running.

What it looks like: a route works fine at localhost:3000/api/..., then returns a 500 once deployed, with no obvious clue on the page itself.

Why it happens: usually one of two things — a server-side environment variable missing in production (same root cause as #3, but server-side), or a runtime mismatch: code using a Node-only API (like fs or a native database driver) while the route is set to run on the Edge runtime.

The fix: open the Vercel dashboard → your deployment → Functions/Logs tab and read the actual stack trace rather than guessing. Add any missing env vars, and if the error mentions an unsupported module, switch the route back to the Node runtime:

// app/api/route.ts
export const runtime = 'nodejs' // instead of 'edge'

What it looks like: you update content in your CMS or database, redeploy, and the live site keeps showing the old version.

Why it happens: in the App Router, fetch caches responses by default unless told otherwise. Without an explicit cache setting, Next.js happily keeps serving the old cached response even after a fresh deploy.

The fix: choose a caching strategy on purpose, per fetch call.

// Always fresh
fetch(url, { cache: 'no-store' })
// Refresh at most once every 60 seconds
fetch(url, { next: { revalidate: 60 } })

1. Node version in package.json matches the version set in Vercel.
2. Lockfile is committed and up to date.
3. Every import's casing matches the actual filename.
4. All required environment variables are added in the Vercel dashboard, per environment.
5. Every external image domain is listed in next.config.js.
6. You've checked Functions/Logs after deploying anything touching an API route.
7. Each fetch call has an intentional cache or revalidate setting.

None of these are exotic bugs — they're the same handful of gotchas every Next.js developer runs into sooner or later. Once you know the pattern, a red deploy log stops being scary and turns into a two-minute fix.