Immutable solution version
Diagnose Netlify serverless function failures: timeouts, 502s, and bundling errors
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 msThe browser sees a 502. Synchronous functions have a 10-second execution limit by default.
Fixes, in order of preference:
Make the work fit. Add
console.time/console.logmarkers 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.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.
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:
Runtime file reads fail (
ENOENTon 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/**").
Native modules break under esbuild (sharp, sqlite3, canvas, ...): they can't be inlined into the bundle. Ship them as-is in
node_modulesinstead:
[functions]
external_node_modules = ["sharp"]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 inlined3. Checklist
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).502 without a timeout → read the exception; then
included_files,external_node_modules,node_bundler.404 → functions directory config (relative to base) and a local
netlify buildto see what's emitted.Bundle deploy failures → esbuild plus pruned
included_files; 250 MB unzipped is the ceiling.- 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>