Fix 502 Bad Gateway on Vercel: Environment Variable Guide

When a Vercel deployment returns a 502 Bad Gateway, the culprit is often a missing or empty environment variable. This guide walks you through the diagnostic steps, fixes, and when to seek escalation, ensuring your serverless functions run smoothly.

Problem Overview

A Vercel deployment that returns a 502 Bad Gateway often crashes its serverless function before it can respond. The most common trigger is a required environment variable that is either absent or empty at runtime.

Common Causes

Build‑time environment variable not exposed to the runtime.
Variable defined only for Production, not for Preview.
Variable value is an empty string.
Typo in the variable name inside code.
Variable defined in the Vercel dashboard but not in vercel.json for serverless functions.

Cause/Diagnostic Table

Cause	Diagnostic Sign	Immediate Fix
Variable missing at runtime	Stack trace starts with `ReferenceError: is not defined`	Define the variable in the correct environment.
Variable present but empty	Stack trace shows `TypeError: Cannot read property … of undefined` or similar.	Set a non‑empty value.
Variable defined only for Production	Works in Production, fails in Preview.	Add variable to Preview environment.
Variable defined but not exposed to runtime	Function starts but throws on first request.	Expose via `vercel.json` or dashboard.
Typo in code	ReferenceError with unexpected variable name.	Correct the name in code.

Step‑by‑Step Checks

Check Deployment Logs
Navigate to the Vercel dashboard → Deployments → select the failing deployment → Logs. Look for a stack trace that mentions a variable name.
List Environment Variables
Run from the project root:
```
vercel env ls
```
Ensure the variable appears under the correct environment (Production or Preview) and that its value is not an empty string.
Verify Exposure to Runtime
Open vercel.json (create if missing) and add:
```
{
  "functions": {
    "api/**.js": {
      "runtime": "nodejs18.x",
      "env": ["MY_SECRET"]
    }
  }
}
```
Replace MY_SECRET with the actual variable name.
Test Locally
Run the function with the same environment variables:
```
vercel dev
```
Confirm the function starts without throwing.
Redeploy
Push a commit or trigger a redeploy from the dashboard. The deployment should now succeed and the 502 should disappear.

Fixes and Validation

Define the missing variable in the Vercel Dashboard under the appropriate environment.
For Preview deployments, duplicate the variable under the Preview tab.
Ensure the variable value is not an empty string; even a placeholder like placeholder will satisfy the runtime.
Update vercel.json to list the variable in the env array for any serverless function that needs it.
After redeploy, verify the logs no longer contain the ReferenceError or TypeError.

Escalation Criteria

After performing all checks, the 502 persists and logs show no environment‑related errors.
Logs indicate other runtime failures (e.g., memory exhaustion, timeouts).
The project uses a custom runtime or framework that may handle env vars differently.
If the issue appears only in production, consider inspecting Vercel’s environment variable precedence or reviewing the build configuration.

Practical Checklist

[ ] Verify variable exists in the correct environment tab.
[ ] Confirm variable value is non‑empty.
[ ] Ensure variable is exposed to runtime via vercel.json or dashboard.
[ ] Run vercel dev locally to catch errors early.
[ ] Redeploy and confirm 502 is resolved.
[ ] If unresolved, open a support ticket with logs and configuration details.

Limitations

This guide focuses exclusively on 502 errors caused by missing or mis‑configured environment variables. It does not address other 502 triggers such as timeouts, memory limits, or network failures. For those scenarios, consult Vercel’s documentation on Function Timeouts and Resource Limits.

Diagnosing 502 Bad Gateway in Vercel: Missing or Mis‑Configured Environment Variables