Diagnosing 502 Bad Gateway in Netlify Functions: A Step‑by‑Step Guide

Problem Overview

A 502 Bad Gateway error from a Netlify Function often appears as a blank page or a generic error message in the browser. It indicates that the function layer failed to return a valid HTTP response to Netlify’s proxy. The root cause can be a timeout, runtime mismatch, missing package, export issue, or an undefined environment variable. This guide walks through a repeatable diagnostic process, shows how to confirm each hypothesis, and gives targeted fixes.

Common Causes & Quick Reference Table

Cause	Typical Symptoms	Immediate Fix
Lambda Timeout (exceeds 10 s)	Long‑running logs, 502 after a few seconds	Optimize code or split into smaller functions
Runtime Mismatch	Runtime error stack trace, "Cannot find module"	Set correct runtime in netlify.toml
Missing Dependencies	"Cannot find module 'foo'" in logs	Run npm install and redeploy
Export/Handler Error	"handler is not a function" or syntax error	Ensure exports.handler = async (event) => { … }
Undefined Env Var	Reference error in logs, stack trace shows process.env.MY_VAR	Set env var in Netlify UI or .env

Diagnostic Checklist

1. Verify Function Logs
   • Navigate to Functions → your‑function in the Netlify UI.
   • Check the most recent invocation log; look for stack traces or error messages.
2. Run Locally with Netlify Dev

   netlify dev
   # Trigger the function via the local URL, e.g. http://localhost:8888/.netlify/functions/hello
   

   Observe console output for timeouts or missing modules.

3. Confirm Runtime Version

   Open netlify.toml and locate the runtime setting under [functions]. If absent, Netlify defaults to Node 12 on the free tier.

   [functions]
     runtime = "nodejs18.x"
   

4. Check Dependencies

   Run npm ls to ensure all imports resolve. If a package appears missing, run npm install <package> and commit package.json and package-lock.json.

5. Inspect Handler Export

   Open the function file (e.g., functions/hello.js) and confirm the exported symbol is named handler and is a function.

   exports.handler = async (event, context) => {
     // ...
   };
   

6. Validate Environment Variables

   In the Netlify dashboard, go to Site settings → Build & deploy → Environment. Ensure any process.env.* referenced in the code has a value.

7. Test Timeout

   Introduce a deliberate await new Promise(r => setTimeout(r, 12000)) in the handler. If the function still returns 502 after 10 s, the timeout limit is enforced.

Targeted Fixes

• Timeout Issues

  Refactor long‑running logic into separate functions or use asynchronous queues (e.g., Netlify Functions + AWS SQS). Avoid blocking code.

• Runtime Mismatch

  Update netlify.toml to match the Node version used locally. Commit and redeploy.

• Missing Dependencies

  Run npm ci to install exactly the versions in package-lock.json. Verify that the lock file is committed.

• Export/Handler Errors

  Ensure the file exports a default handler function. If using ES modules, add type="module" in package.json and export as export const handler = async (event) => { … }.

• Undefined Env Vars

  Set missing vars via the Netlify UI or a .env file in the project root. Remember that .env files are not automatically uploaded; you must add the variables in the dashboard for production.

Escalation Criteria

If after applying the above fixes the function still returns 502, consider:

• Complexity beyond a single function’s scope—split logic.
• Third‑party API rate limits or authentication failures—check external logs.
• Unexpected network errors—use node-fetch with proper error handling.
• Potential Netlify platform issue—open a support ticket with logs attached.

Practical Verification Checklist

# After each fix, run:
netlify build
# Deploy locally to confirm the function responds:
netlify dev
# Check the function URL for a 200 response.

When the function returns a JSON object with a statusCode: 200 and a body, the 502 is resolved. If the logs still show a timeout or runtime error, revisit the earlier steps.

Limitations & Risks

• Free tier functions are limited to 10 s; setting a longer timeout can incur additional costs.
• Changing the runtime may break other functions that rely on older Node features.
• Environment variables set in the Netlify UI are immutable via netlify.toml; ensure they match across environments.
• Local netlify dev does not emulate all production nuances (e.g., cold starts), so always test on Netlify after deployment.

Conclusion

By following this structured diagnostic flow—logs, local dev, runtime check, dependency audit, handler validation, and env‑var verification—you can pinpoint the root cause of a 502 Bad Gateway in Netlify Functions quickly. Apply the targeted fix, re‑deploy, and confirm with the verification checklist. If the issue persists, escalated support with detailed logs is the next step.