Vercel Build Failed on `npm run build`: 3 Fixes (Node, Env, Output Dir)

Project: Astro 5 static blog Local: npm run build ✅ in 18s Vercel: ❌ exit code 1

TL;DR

• Pin Node 20+ in package.json engines or vercel.json.
• Add build-time env vars (e.g. SITE_URL) for Production AND Preview.
• Set outputDirectory to dist/public and framework: null.

Error #1: Node version

error astro@5.x: The engine "node" is incompatible with this module. Expected ">=18.17.0". Got "18.15.0"

Vercel defaulted to older Node. Fix in package.json:

"engines": { "node": ">=20" }

Or vercel.json:

{ "build": { "env": { "NODE_VERSION": "20" } } }

Redeploy — don't just save settings.

Error #2: Build script vs install script

"scripts": {
  "build": "astro build && node scripts/generate-feed.mjs"
}

Feed script imported SITE_URL from env — undefined on Vercel:

TypeError: Cannot read properties of undefined (reading 'replace')

Vercel → Settings → Environment Variables → add SITE_URL for Production AND Preview.

Error #3: Wrong output directory

Error: No Output Directory named "dist" found after the Build completed.

Astro outputs to dist/. Vercel assumed public/.

vercel.json:

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": null
}

Setting framework: null stops Vercel from auto-detecting Next.js wrongly.

Debug workflow I use now

vercel link
vercel env pull .env.local
vercel build

vercel build runs the same build locally as remote. Caught error #2 before push.

Build logs tip

Expand "Building" → search ERR!. The actual error is often 40 lines above Command "npm run build" exited with 1.

Final working vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm ci",
  "framework": null
}

Verify

1. vercel build passes locally
2. Push → deployment green
3. Preview URL serves CSS (not unstyled HTML — sign of wrong output dir)

FAQ

Why does npm run build work locally but fail on Vercel?

Common causes: different Node version, env vars only set locally, wrong output directory, or Vercel auto-detecting the wrong framework.

How do I debug Vercel builds locally?

Run vercel link, vercel env pull .env.local, then vercel build — it mirrors the remote build environment.

What output directory does Astro use on Vercel?

Astro outputs to dist/ by default. Set outputDirectory: dist in vercel.json and framework: null to prevent Next.js auto-detection.