How to Fix Failed Deployments on Vercel/Netlify | Cheatsheet

Your code works locally. You push to deploy. It fails. Deployment failures are uniquely frustrating because everything runs perfectly on your machine, but the build server disagrees.

AI-generated code is especially prone to deployment failures because AI doesn’t know about your deployment environment — missing environment variables, case-sensitive file systems, and stricter build settings all conspire to break things.

Why Does It Work Locally but Fail on Deploy?

Your local machine has things the build server doesn’t:

Environment variables in .env files (not committed to git)
Case-insensitive file system (macOS/Windows) vs. case-sensitive (Linux build servers)
Cached node_modules with extra packages you installed and forgot about
Looser TypeScript/ESLint settings or warnings you ignored

5 Common Deployment Failures

1. Missing Environment Variables

The #1 cause of deployment failures. Your .env file isn’t on the server.

Error: Missing required environment variable: DATABASE_URL
// or silently: API calls return undefined, pages crash

Fix:

Vercel: Settings → Environment Variables → add each one
Netlify: Site settings → Environment variables → add each one
Don’t forget to set them for all environments (Production, Preview, Development)

# Check which env vars your code needs:
grep -r "process.env\." src/ --include="*.ts" --include="*.js" | 
  grep -oP 'process\.env\.[\w]+' | sort -u

2. Case-Sensitive File Imports

macOS is case-insensitive. Linux (the build server) is case-sensitive.

// Works on Mac, FAILS on Vercel:
import Header from './components/header';  // file is actually Header.tsx

// Fix: match exact case
import Header from './components/Header';

# Find case mismatches:
git config core.ignorecase false
# Then git will show renamed files

3. TypeScript / ESLint Errors Treated as Build Failures

Locally, warnings don’t stop you. On deploy, they might.

Type error: Property 'x' does not exist on type 'Y'.
// Build fails because Next.js treats TS errors as fatal

Fix — either fix the errors or (temporarily) configure to allow them:

// next.config.js — NOT recommended for production
module.exports = {
  typescript: { ignoreBuildErrors: true },
  eslint: { ignoreDuringBuilds: true },
};

Better: actually fix the TypeScript errors. Ask AI:

Fix all TypeScript errors in this file: [paste code]

4. Build Command or Output Directory Wrong

The platform doesn’t know how to build your project, or looks in the wrong directory for output.

Vercel defaults:

Framework	Build Command	Output Directory
Next.js	`next build`	`.next`
Astro	`astro build`	`dist`
Vite/React	`vite build`	`dist`

Fix: Check your platform settings:

Vercel: Settings → General → Build & Output Settings
Netlify: Site settings → Build & deploy → Build settings

5. Dependencies Not Installing

A package is in your code but not in package.json, or the lockfile is out of sync.

# Error: Cannot find module 'some-package'
# It's installed locally in node_modules but not listed in package.json

# Fix: make sure it's in package.json
npm install some-package --save

# Then commit package.json AND package-lock.json
git add package.json package-lock.json
git commit -m "add missing dependency"

Step-by-Step Fix Process

Step 1: Read the Build Log

Both Vercel and Netlify show full build logs. The error is in there.

Vercel: Deployments → click the failed deployment → Build Logs
Netlify: Deploys → click the failed deploy → Deploy log

Search for error, Error, or failed in the log.

Step 2: Reproduce Locally

# Simulate production build
npm run build

# If that passes, check env vars:
# Temporarily unset all env vars and build again
env -i HOME=$HOME PATH=$PATH npm run build

Step 3: Check the Usual Suspects

# 1. Missing env vars?
grep -r "process.env\." src/ --include="*.ts" --include="*.js"

# 2. Case-sensitive imports?
git diff --name-only --diff-filter=R  # renamed files

# 3. Missing dependencies?
npm ls --all 2>&1 | grep "MISSING"

# 4. Lockfile committed?
git ls-files package-lock.json  # should show the file

Step 4: Fix and Retry

After fixing, push again. Most platforms auto-deploy on push.

git add .
git commit -m "fix: deployment build errors"
git push

Platform-Specific Fixes

Vercel

# Force clean install (ignore cache)
# Settings → General → Build & Output → Override Install Command:
npm ci

# Node.js version mismatch? Set it:
# Settings → General → Node.js Version → 18.x or 20.x

# Or in package.json:
{
  "engines": {
    "node": ">=18.0.0"
  }
}

Netlify

# netlify.toml — explicit build configuration
[build]
  command = "npm run build"
  publish = "dist"

[build.environment]
  NODE_VERSION = "20"
  NPM_FLAGS = "--legacy-peer-deps"

Common Vercel/Netlify Gotchas

API routes — Netlify uses Netlify Functions, not the same as Next.js API routes
Image optimization — next/image works on Vercel but needs a plugin on Netlify
Redirects — Different syntax per platform (vercel.json vs _redirects)
Build memory — Free tiers have RAM limits; large builds may OOM

🤖 Prompt to Fix This

My deployment is failing on [Vercel/Netlify]. Here's the build log error:

[PASTE THE RELEVANT ERROR SECTION FROM BUILD LOG]

My project:
- Framework: [Next.js 14 / Astro / Vite React]
- Node version: [18/20]
- The build works locally with `npm run build`

My environment variables are:
[LIST THE ENV VAR NAMES — not values — that you've set]

Please:
1. Diagnose what's causing the deployment failure
2. Tell me if this is an env var, dependency, or code issue
3. Give me the exact fix
4. Show me how to verify it works before pushing

Prevention Checklist

Before every deployment:

□ npm run build passes locally
□ All env vars are set in deployment platform
□ package-lock.json is committed
□ No case-sensitivity issues in imports
□ TypeScript compiles with zero errors
□ No hardcoded localhost URLs in production code

🧙 Debug Wizard — Paste your error for AI-powered fix suggestions
📖 Debugging with AI — Full debugging workflow
📋 Project Setup Cheatsheet — Set up projects to deploy cleanly
📋 Security Checklist — Don’t leak env vars