Vercel Not Working? How to Fix Deployments, Builds, and Edge Functions
Troubleshoot Vercel deployment failures — build errors, 404 after deploy, environment variables not loading, Node.js version mismatches, and Edge Function 500 errors.
Common errors and fixes
Deployment Stuck or Failed
First check whether the issue is Vercel-side or in your project. Visit vercel.com/status or prismix.dev/service/vercel for live incident data. To reproduce locally with full debug output:
vercel --debug- Functions tab: open the deployment in the Vercel dashboard — the Functions tab shows per-function memory usage and execution duration for each invocation.
- Default timeout: Serverless Functions time out at 10 seconds on Hobby plans; Pro plans allow up to 300 seconds. Set
maxDurationin your route config if needed. - Stuck deployments: a deployment queued for more than 10 minutes usually indicates a Vercel platform issue — check the status page and cancel + redeploy.
404 After Deploy
A successful build that returns 404 on all or some routes is almost always a routing conflict between vercel.json rewrites and your framework's router. Check the Output tab in your deployment to confirm expected routes were generated:
# reproduce routing locally
vercel dev- vercel.json rewrites vs Next.js App Router: a catch-all rewrite like
{"source": "/(.*)", "destination": "/index.html"}will intercept all requests before Next.js handles them — remove it or make it more specific. - Output tab: under Deployments → select deployment → Output, confirm your page routes appear in the generated routes list.
- App Router pages: for Next.js App Router, each route needs a
page.tsx(notindex.tsx) at the correct directory depth underapp/.
Environment Variables Not Loading
.env.local is intentionally excluded from Vercel deployments — it is local-only. All production variables must be added in the Vercel dashboard:
# Vercel dashboard path
# Project → Settings → Environment Variables
#
# For client-side access in Next.js, prefix with NEXT_PUBLIC_:
NEXT_PUBLIC_API_URL=https://api.example.com # exposed to browser
DATABASE_URL=postgres://... # server-only- NEXT_PUBLIC_ prefix: only variables prefixed with
NEXT_PUBLIC_are inlined into the client bundle at build time — all others are server-only. - Redeploy required: adding or changing a variable in the dashboard does not update live deployments — trigger a new deployment (Redeploy button or push a commit) for the change to take effect.
- Environments: Vercel separates Production, Preview, and Development environments — make sure the variable is enabled for the correct environment.
Build Errors
Reproduce build failures locally before pushing to avoid slow feedback loops. Use vercel build which sets the same VERCEL=1 environment variable that Vercel sets during CI builds:
# reproduce the Vercel build locally
vercel build
# check the Node.js version Vercel will use
node --version
# pin version in package.json
# "engines": {"node": "20"}package-lock.json and yarn.lock, Vercel may choose the wrong package manager. Delete the lockfile you are not using and commit the change.
- Node version: add
"engines": {"node": "20"}topackage.json— without it Vercel defaults to an older Node version that may not support your code. - VERCEL=1 env var: Vercel sets
VERCEL=1during builds — use it in conditional build logic to detect the Vercel environment. - npm ci vs yarn:
npm cirequirespackage-lock.json; if Vercel detectsyarn.lockit will useyarn install --frozen-lockfileinstead — a mismatched lockfile causes the install to fail.
Edge Functions / API Routes Returning 500
Edge Functions run in a V8 isolate — they cannot use Node.js built-in modules. If your API route imports fs, path, or any native Node module it will fail silently at runtime with a 500. Set the runtime explicitly:
// app/api/hello/route.ts
export const runtime = 'edge';
export function GET() {
return new Response('Hello from the edge');
}- No Node.js built-ins: Edge runtime cannot use
fs,path,crypto(use the Web Crypto API instead), or any package that depends on them. - 1 MB bundle limit: Edge Functions have a 1 MB compressed bundle limit — large dependencies that work in Serverless Functions will cause Edge deployment to fail.
- Function Logs: to see runtime errors go to Vercel dashboard → Deployments → select the deployment → Functions tab — each function shows invocation logs with error details.
Know when Vercel has an outage
Free email alerts. Star Vercel on Prismix — no credit card needed.
FAQ
Why is my Vercel deployment failing?
Builds fail for Node version mismatch, lockfile conflicts, or missing environment variables. Add "engines": {"node": "20"} to package.json, ensure only one lockfile exists, and check all required env vars are set in the Vercel dashboard.
How do I check Vercel status?
Visit vercel.com/status for the official Vercel status page. For automated monitoring and incident history, check prismix.dev/service/vercel which polls Vercel status every 5 minutes.
Why are my environment variables undefined in production?
Variables in .env.local are never deployed — add them in the Vercel dashboard under Settings → Environment Variables. A redeploy is required after adding variables for them to take effect.
How do I fix Vercel 404 errors after deploy?
Check vercel.json for catch-all rewrite rules that conflict with your framework router. Open the deployment in the Vercel dashboard and inspect the Output tab to confirm expected routes appear. Run vercel dev locally to reproduce routing behavior before pushing.
