SteadyNode

Netlify · HTTP 502

Netlify 502: Invalid Function Response

Diagnose Netlify 502 responses when a function crashes or returns an invalid payload. Check handler exports, response format, runtime logs, and deployment output.

Origin / Application

Decode a CDN or gateway error

Paste a captured HTTP response or enter a status and headers. Only the status and response headers are sent; common credential headers are filtered first.

Supports raw headers, full HTTP responses, JSON with status/statusCode and headers, cURL -v/-i response output, and HAR exports. HAR selects a server error first. cURL commands are never executed; request headers, response bodies, and common credential headers are excluded.

Diagnostic report

Error code / name

NETLIFY-FUNCTION_INVALID_RESPONSE

Fault domain

Origin / Application

Why it happened

The function failed during execution or returned a value that the Netlify adapter could not translate to HTTP. Invalid exports, an unhandled promise rejection, and malformed headers are common triggers.

Actionable fixes

  1. Find the matching x-nf-request-id in function logs and inspect the first exception.
  2. Return a standards-compliant Response or the exact shape required by the selected function runtime.
  3. Test the production build and environment variables rather than relying only on a local development server.

Why this error happened

The function failed during execution or returned a value that the Netlify adapter could not translate to HTTP. Invalid exports, an unhandled promise rejection, and malformed headers are common triggers.

Actionable fixes

  1. Find the matching x-nf-request-id in function logs and inspect the first exception.
  2. Return a standards-compliant Response or the exact shape required by the selected function runtime.
  3. Test the production build and environment variables rather than relying only on a local development server.

Network failure point

Client -> Netlify Edge -> function adapter -> throw or malformed response -> X 502

Verify origin directly via CLI

curl -sS -v --max-time 30 https://example.com/.netlify/functions/health -o /dev/null

Configuration fix

netlify/functions/health.tstypescript
export default async () => {
  return new Response(JSON.stringify({ status: "ok" }), {
    status: 200,
    headers: { "content-type": "application/json" },
  });
}

Catch this failure before it becomes an outage

SteadyNode's HTTP checks detect Netlify 502 responses at the public endpoint and preserve request identifiers for faster correlation with function logs.

No credit card required.

Start for free

Frequently asked questions

Can a malformed function response cause Netlify 502?

Yes. A runtime adapter may return 502 when a function throws or produces an invalid HTTP response.

Why does the function work locally but fail on Netlify?

Build output, environment variables, runtime versions, and function export conventions can differ between local and deployed execution.

More CDN and gateway error guides

Cloudflare

Vercel and Netlify

AWS CloudFront and ALB

Fastly

Heroku and Render

Nginx and Envoy