Vercel runtime errors

Status: 🟩 COMPLETE (🟦 LIVING — Vercel runtime evolves with platform updates) Last updated: 2026-06-21 Plain-English tagline: Errors that happen AFTER deploy succeeds — function timeouts, 500s, edge runtime quirks, the Vercel-specific runtime gotchas. For build-time failures, see Build errors.

---

What this is

A reference for errors that show up in Vercel Runtime Logs (the live log stream from your serverless and edge functions after a successful deploy). These are different from build errors — the deploy worked, but something fails when a real request hits your app.

For build-time problems (npm run build failing): see Build errors 🟩.

---

Where to look

In the Vercel dashboard:

• Deployments tab → click a deployment → “Runtime Logs”
• Filter by route, status code, deployment
• Logs stream in real time; recent ones are searchable

In CLI: vercel logs --follow tails recent logs.

---

”Function execution timed out”

What it means: Your serverless function ran past its time limit.

Limits by tier (as of 2026):

• Hobby: 10 seconds
• Pro: 60 seconds default, configurable up to 800 seconds via vercel.json
• Enterprise: longer

Common causes:

1. Long-running LLM call. Anthropic / OpenAI calls can take 5–30 seconds for big outputs.
2. Synchronous heavy computation. Image processing, large CSV generation.
3. Database query that scans a large table. Missing indexes.
4. External API that’s slow or hanging.

Fix paths:

• Increase the limit (Pro tier only). In vercel.json:

  {
    "functions": {
      "app/api/heavy/route.ts": { "maxDuration": 60 }
    }
  }

• Stream the response. For LLM calls, use Server-Sent Events so the user sees output as it generates. The function stays active until done, but the user isn’t waiting silent.
• Move work to background. Trigger an Edge Function or a queue (Inngest, QStash); respond to the user immediately; finish the work async.
• Add database indexes for slow queries.

Reference: Serverless functions 🟩, Vercel 🟩 🟦

---

“Function invocation failed: Module ‘X’ not found at runtime”

What it means: The build succeeded (TypeScript / bundler resolved the import) but at runtime, the file isn’t where the function expects.

Common causes:

1. Native dependencies that aren’t included in the deploy package (Sharp, sqlite3, others).
2. Dynamic require() calls the bundler couldn’t trace.
3. External files (images, JSON) referenced via fs.readFileSync without including them in deploy.
4. devDependencies used in production code. Vercel strips dev deps; if your function imports one, it fails at runtime.

Fix:

• Move the dep into dependencies (from devDependencies).
• For external files: import them as ES modules (import data from "./data.json") instead of fs.readFile. Bundlers include imported files; fs references need explicit config.
• For native deps: add to serverExternalPackages in next.config.js and ensure they’re in dependencies.

---

”Edge Function: ReferenceError: process is not defined”

What it means: You’re using Node.js APIs (process.env, fs, path, Buffer) in code that runs on the Edge runtime. Edge functions use Web Platform APIs only.

Fix:

• Move to the Node.js runtime — at the top of the route file:

  export const runtime = "nodejs";  // default; you only need this if previously set to edge

• OR rewrite to use Web Platform APIs:
  • process.env.X → works in Edge for vars set in Vercel dashboard (since 2024) but not in all cases; check
  • fs.readFile → not available; preload via import
  • Buffer → use Uint8Array / TextEncoder
  • crypto → use globalThis.crypto.subtle

Reference: Edge functions 🟩, Regions & edge 🟩

---

“Edge Function: 1MB code size limit exceeded”

What it means: Edge functions ship to ~400 global locations; the bundle for each is capped.

Limits:

• Hobby: 1 MB
• Pro: 2 MB
• Enterprise: 4 MB

Fix:

• Move to the Node.js runtime if size constraints aren’t workable.
• Lazy-load heavy modules with await import() instead of top-level imports.
• Audit dependencies — pick lighter alternatives (e.g. date-fns instead of moment).

---

”FUNCTION_INVOCATION_TIMEOUT” or “FUNCTION_INVOCATION_FAILED”

What they mean:

• TIMEOUT — same as “Function execution timed out” above.
• FAILED — generic. Read the actual logs; the underlying error is usually obvious there.

These appear as the response code on the request side; the actual stack trace is in Runtime Logs.

---

”504 Gateway Timeout” from your custom domain

What it means: Vercel’s edge couldn’t get a response from your function within Vercel’s own timeout.

Common causes:

• Function took longer than the tier limit
• Function crashed silently
• Database connection hanging (Supabase down, network issue)

Fix: check the Runtime Logs for the function. The actual error will be there.

---

”Body exceeded 4.5 MB” / “REQUEST_BODY_TOO_LARGE”

What it means: A request body sent to a Vercel Function exceeded the platform limit.

Limits: 4.5 MB for Hobby; Pro can be configured higher.

Fix:

• For file uploads: use signed URLs (Supabase Storage, S3) and upload directly to storage from the browser. Don’t proxy uploads through your function.
• For large JSON payloads: chunk them, paginate them, or compress (gzip).

---

”Response body exceeded N MB”

What it means: Your function returned a body larger than the limit (~4.5 MB for Hobby).

Fix:

• Stream the response — for large payloads, send chunks as you generate them.
• Paginate — return a page, with a cursor for the next.
• Compress — gzip the response (Next.js handles this automatically for most cases).

---

”TypeError: fetch failed” or “ECONNREFUSED” in production

What they mean: Your function tried to call an external service that wasn’t reachable.

Common causes:

1. Wrong URL (env var not set / incorrect / pointing at localhost in production).
2. External service down or rate-limiting.
3. CORS / firewall blocking the request.
4. DNS resolution failure.

Fix:

• Check env vars in Vercel dashboard. localhost:3000 doesn’t exist on Vercel.
• Add retries with backoff for flaky third-party services.
• Log the URL to verify what’s actually being called.

---

”MIDDLEWARE_INVOCATION_FAILED”

What it means: Your Next.js middleware (middleware.ts) threw or returned something invalid.

Common causes:

• Throwing without catching
• Calling Node.js APIs (middleware runs on the Edge runtime, same constraints)
• Returning a malformed NextResponse

Fix: wrap middleware logic in try/catch; verify Edge-runtime compatibility; return NextResponse.next() for the default pass-through case.

---

”Cannot find name ‘self’ or ‘WebSocket’ in Edge function”

What it means: Type definitions for the Edge runtime aren’t included.

Fix: in tsconfig.json:

{
  "compilerOptions": {
    "types": ["node"],
    "lib": ["ES2022", "WebWorker", "DOM"]
  }
}

The WebWorker lib includes Edge-runtime globals.

---

”Build deployed to a different region than expected”

What it means: You configured regions: ["syd1"] in vercel.json but functions are deploying to iad1.

Common causes:

• vercel.json not committed / not in the deployed branch
• Misconfigured (e.g. region instead of regions)
• Free tier limits — some region configurations require Pro

Fix: verify the deployed vercel.json. Check the function detail page on Vercel dashboard — it shows the region the function is actually pinned to.

Bible Quest pins to syd1 via vercel.json to match the Supabase project region; this avoids ~150ms latency on every database query.

---

”Static page generation failed at runtime”

What it means: A page configured for ISR (Incremental Static Regeneration) failed to regenerate.

Common causes:

• Data source temporarily unavailable
• Type error introduced in a recent deploy that only fires during regeneration
• Database query timed out

Fix: check Runtime Logs for the specific page during the regeneration attempt. Fix the underlying issue; ISR will retry on the next request.

---

”Vercel Analytics: events not being recorded”

What it means: Vercel Analytics package is installed but events aren’t showing in the dashboard.

Common causes:

• Analytics not enabled in dashboard for the project
• Free tier limits / sampling
• @vercel/analytics package version mismatch with Next.js
• Browser extension blocking the analytics endpoint (ad blockers)

Fix: verify the package version matches your Next.js version, enable analytics in the dashboard, test in a clean incognito window.

---

See also

• Common errors — index 🟩
• Build errors 🟩 — for npm run build / deploy failures
• Supabase errors 🟩 🟦 — if the runtime error is a Supabase query
• Browser errors 🟩 — for client-side issues
• Vercel 🟩 🟦 — the textbook
• Serverless functions 🟩
• Edge functions 🟩
• Regions & edge 🟩
• How-to: Debug a Vercel build failure 🟩
• Vercel CLI cheat sheet 🟩 🟦

---

Sources

• Vercel docs — Functions
• Vercel docs — Limits
• Vercel docs — Troubleshooting
• Next.js — Edge runtime