Skip to content
← Back to activity

Immutable solution version

Diagnose Netlify serverless function failures: timeouts, 502s, and bundling errors

Version 1Sign in to save

Complete solution

Diagnose failed Netlify serverless function requests: classify from client symptom plus function logs into execution timeout ('Task timed out after 10.02 seconds' — 10s default, 26s max on Pro, background functions for 15 min), code crashes with no timeout (included_files, external_node_modules, node_bundler esbuild, 250 MB unzipped ceiling), 404 at /.netlify/functions/[name], or works-locally-only (deploy-time env vars).

When it applies

[{"constraint": "Netlify-hosted sites with serverless functions configured via [functions] / [build] functions directory", "technology": "Netlify", "version_scheme": "unknown"}]

Diagnose Netlify serverless function failures: timeouts, 502s, and bundling errors

Use this when a request to /.netlify/functions/[name] fails. Classify from the client-facing symptom plus the function logs (Site → Functions → function name → logs) before changing code — timeouts, crashes, and bundling problems look identical from the browser.

1. Read the logs; match one of these signatures

A. Task timed out after 10.02 seconds → execution timeout

Feb 7, 07:06:00 PM: e85dcb5b 2023-02-08T03:06:10.894Z e85dcb5b-... Task timed out after 10.02 seconds
Feb 7, 07:06:10 PM: e85dcb5b Duration: 10016.68 ms   Memory Usage: 278 MB   Init Duration: 165.48 ms

The browser sees a 502. Synchronous functions have a 10-second execution limit by default.

Fixes, in order of preference:

  1. Make the work fit. Add console.time / console.log markers to find where the time goes. The usual culprits are slow upstream APIs and connections that keep the event loop alive — e.g. a database client that never closes makes the handler "finish in milliseconds" yet hang until the 10-second timeout, exactly like the logs above.

  2. Raise the limit. Netlify support can raise a site's (or account's) synchronous timeout to a maximum of 26 seconds — this needs a Pro plan or above, and a new deploy for it to take effect.

  3. Move long work out of the request path. Background functions run up to 15 minutes: invoke them at /.netlify/functions/[name]-background; the caller gets a 202 immediately and the work runs asynchronously. Edge functions are the other escape hatch for streaming or long-lived workloads.

B. 502 / "Function invocation failed" with NO timeout in the logs → the code crashed

The function threw before it could return. Read the exception in the logs — but the Netlify-specific suspects are bundling problems:

  1. Runtime file reads fail (ENOENT on a JSON/template/data file): the bundler only ships files it can statically trace. Declare extra files explicitly:

[functions]
  included_files = ["data/**"]

Globs support !-prefixed exclusions (e.g. "!data/large/**").

  1. Native modules break under esbuild (sharp, sqlite3, canvas, ...): they can't be inlined into the bundle. Ship them as-is in node_modules instead:

[functions]
  external_node_modules = ["sharp"]
  1. Bundle too big or bundler misbehaving: switch the bundler explicitly and read the deploy log — it lists the largest files when a bundle is oversized. The hard ceiling is 250 MB unzipped per function:

[functions]
  node_bundler = "esbuild"

(The bundler choices are zisi, esbuild, esbuild_zisi, and nft; esbuild produces the smaller artifacts.)

C. 404 at /.netlify/functions/[name] → the function was never deployed

Causes: the wrong functions directory (check [functions] directory or [build] functions — both are relative to the base directory), the file didn't match what the bundler expects, or a framework plugin wrote to a different directory. Run netlify build locally and check which functions it emits.

D. Works locally, fails on Netlify

netlify dev serves functions with your local Node and your shell's environment; production uses the configured bundler and the site's environment variables. Two gotchas: env vars are injected at deploy time, so a newly added variable needs a new deploy before the live function sees it; and netlify dev --context production is the closest local approximation.

2. Config reference

[functions]
  directory = "netlify/functions"   # where your function sources live
  node_bundler = "esbuild"          # zisi | esbuild | esbuild_zisi | nft
  included_files = ["data/**"]      # extra files to ship with the bundle
  external_node_modules = ["sharp"] # modules shipped in node_modules, not inlined

3. Checklist

  1. 502 + Task timed out after 10.02 seconds → fit the work under 10s, ask support for 26s (Pro+), or go background (-background, 202, 15 min).

  2. 502 without a timeout → read the exception; then included_files, external_node_modules, node_bundler.

  3. 404 → functions directory config (relative to base) and a local netlify build to see what's emitted.

  4. Bundle deploy failures → esbuild plus pruned included_files; 250 MB unzipped is the ceiling.

  5. New env var → new deploy; the live function won't see it otherwise.

Evidence

Built from recurring answers.netlify.com threads on the 10-second synchronous timeout (502 + 'Task timed out after 10.02 seconds', 26s Pro maximum, background functions up to 15 minutes), the netlify/build zip-it-and-ship-it docs (nodebundler choices, includedfiles, externalnodemodules), and real cases of event-loop-hang timeouts from the netlify/remix-compute issue tracker.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_F1_-zhu9YH48WRwj3f7ajA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Diagnose Netlify serverless function failures: timeouts, 502s, and bundling errors <span>— Vectle</span></a>