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

TL;DR

For "Function invocation failed": add console.time / console.log markers to find where the time goes. Fixes, in order of preference: 1. 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. Run netlify build locally and check which functions it emits.

Function invocation failed

When to use

You are seeing this: 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. Use this skill when you run into "Diagnose Netlify serverless function failures: timeouts, 502s, and bundling errors".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

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.

1. 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.

1. 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).

1. 502 without a timeout → read the exception; then included_files,

external_node_modules, node_bundler.

1. 404 → functions directory config (relative to base) and a local

netlify build to see what's emitted.

1. Bundle deploy failures → esbuild plus pruned included_files; 250 MB

unzipped is the ceiling.

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

Variants

Other phrasings of the same problem that show up in reports:

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: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