vercel-common-errors

Overview

Diagnose and resolve the most common Vercel errors across three layers: build pipeline, serverless function runtime, and edge network. Each error includes the error code, root cause, and step-by-step fix.

Prerequisites

• Vercel CLI installed
• Access to deployment logs (vercel logs <url>)
• Access to Vercel dashboard for build logs

Instructions

Step 1: Identify the Error Layer

# Check deployment status and error details
vercel inspect <deployment-url>

# View function runtime logs
vercel logs <deployment-url> --follow

# View build logs via API
curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
  "https://api.vercel.com/v13/deployments/dpl_xxx" | jq '.state, .errorMessage'

Three error layers:

1. Build errors — appear during vercel deploy, exit codes in build log
2. Runtime errors — appear when functions are invoked, visible in function logs
3. Edge/routing errors — HTTP errors from Vercel's edge network

Step 2: Build Errors

BUILD_FAILED — Build command exited with non-zero code

Error: Command "npm run build" exited with 1

• Check: vercel.json → buildCommand matches your build script
• Check: all dependencies listed in package.json (not just devDependencies for runtime deps)
• Fix: run npm run build locally to reproduce

MISSING_BUILD_SCRIPT — No build command found

Error: Missing Build Command

• Fix: add "build" to package.json scripts or set buildCommand in vercel.json
• For static sites: set buildCommand to empty string or "true"

FUNCTION_PAYLOAD_TOO_LARGE — Serverless function bundle > 250 MB

Error: The Serverless Function "api/heavy" is 267 MB which exceeds the maximum size of 250 MB

• Fix: add unused packages to .vercelignore, use dynamic imports, split into smaller functions
• Check: @vercel/nft trace output to see what is being bundled

Step 3: Runtime Errors

FUNCTION_INVOCATION_FAILED — Unhandled exception in function

# View the actual error
vercel logs <deployment-url> --output=short

• Common causes: undefined env var, missing database connection, unhandled promise rejection
• Fix: wrap handler in try/catch, verify all env vars are set for the target environment

FUNCTION_INVOCATION_TIMEOUT — Function exceeded max duration

Error: Task timed out after 10.00 seconds

• Hobby: 10s max, Pro: 60s default (up to 300s), Enterprise: 900s
• Fix: optimize database queries, add connection pooling, or move to background processing
• Configure in vercel.json:

{
  "functions": {
    "api/slow-endpoint.ts": {
      "maxDuration": 60
    }
  }
}

NO_RESPONSE_FROM_FUNCTION — Function didn't return a response

• Cause: handler has a code path that doesn't call res.send(), res.json(), or return a Response
• Fix: ensure ALL code paths return a response, including error handlers

FUNCTION_THROTTLED — Too many concurrent function invocations

• Hobby: 10 concurrent, Pro: 1000 concurrent
• Fix: implement client-side retry with backoff, or upgrade plan

Step 4: Edge/Routing Errors

404 NOT_FOUND

• API route 404: verify file is in api/ or pages/api/ directory
• Page 404: check outputDirectory in vercel.json, verify build output contains the file
• Fix: run vercel inspect <url> to see the deployment file listing

504 GATEWAY_TIMEOUT

• Serverless function exceeded its timeout — same as FUNCTION_INVOCATION_TIMEOUT
• Fix: increase maxDuration or optimize function

413 REQUEST_ENTITY_TOO_LARGE

• Request body exceeds 4.5 MB limit
• Fix: use chunked upload, stream the body, or use presigned URLs for large files

DEPLOYMENT_NOT_FOUND

• Deployment was deleted or URL is malformed
• Fix: verify the deployment still exists with vercel ls

Step 5: Environment Variable Errors

ReferenceError: process is not defined (Edge Runtime)

• Cause: using process.env in an edge function
• Fix: Edge Functions can read env vars but only those defined at build time. Ensure vars are set.

Env var undefined in production but works in preview

• Cause: variable scoped to Preview only, not Production
• Fix: check scopes in Settings > Environment Variables, add Production target

# Check which environments have the variable
vercel env ls | grep DATABASE_URL

Quick Diagnosis Flowchart

Error occurred
├── During build? → Check build logs, run `npm run build` locally
├── During function invocation? → Check function logs with `vercel logs`
├── HTTP 404? → Verify file exists in deployment: `vercel inspect`
├── HTTP 500? → Unhandled exception in function code
├── HTTP 504? → Function timeout — increase maxDuration
└── HTTP 429? → Rate limited — implement retry with backoff

Output

• Error layer identified (build, runtime, or edge)
• Root cause diagnosed using logs and inspection
• Fix applied and verified via new deployment
• Prevention measures documented

Error Handling

| Error Code | HTTP | Layer | Quick Fix | |-----------|------|-------|-----------| | BUILD_FAILED | — | Build | Run build locally, check deps | | FUNCTION_INVOCATION_FAILED | 500 | Runtime | Check env vars, add try/catch | | FUNCTION_INVOCATION_TIMEOUT | 504 | Runtime | Increase maxDuration in vercel.json | | FUNCTION_THROTTLED | 429 | Runtime | Reduce concurrency or upgrade plan | | FUNCTION_PAYLOAD_TOO_LARGE | 413 | Build | Reduce bundle size | | NOT_FOUND | 404 | Edge | Verify file paths and routes | | EDGE_FUNCTION_INVOCATION_FAILED | 500 | Edge | Remove Node.js APIs from edge code | | NO_RESPONSE_FROM_FUNCTION | 502 | Runtime | Return response from all code paths |

Examples

Repair a production-only missing environment variable

When a route works in preview but returns a production 500, first confirm the variable’s target scope with vercel env ls without printing its value. Add the secret through the project’s approved secret-management path for the Production target, redeploy a preview with a synthetic health check, and verify only that the variable is present and the route succeeds. Record the deployment URL and remove any temporary diagnostic logging before promoting the fix.

Resources

• Vercel Error Codes
• Function Limitations
• Platform Limits
• Vercel Status Page
• Vercel Logs CLI

Next Steps

For detailed debug bundles, see vercel-debug-bundle.