Netlify function timeout: why you get a 502 and how to fix it
Netlify Functions have a time limit. How to confirm a timeout in the logs, speed up slow functions, and move long work to background or scheduled functions.
· 6 min read · By the Spot Downtime team
A Netlify function that takes too long is stopped by the platform, and the visitor sees an error, usually a 502 or a 504 page. The function didn't crash on its own: the clock ran out. That distinction matters because the fix isn't a bug fix. You either make the work faster, or move it somewhere that is allowed to take longer.
Confirm that it is a timeout
Open the site in the Netlify dashboard, go to Logs, then Functions, and pick the function. A timeout is logged as a message like Task timed out after 30.00 seconds (the number is your limit) together with the request ID. If you see that, you're in the right place. If you see an exception and a stack trace instead, it's a code error; see 500 Internal Server Error.
You can also reproduce from a terminal and time it. A request that fails at almost exactly the same elapsed time every run is a limit, not random flakiness:
time curl -s -o /dev/null -w "%{http_code}\n" https://example.netlify.app/.netlify/functions/reportWhat the limits are
Limits depend on the type of function, and Netlify has changed them over time, so check the current figures for your plan in the Netlify documentation before you plan around them. The pattern is stable, though:
- Synchronous functions (called by a request, the visitor waits) have the shortest limit, in the range of seconds to a minute. The default is lower than the maximum you can configure.
- Background functions (file name ends in
-background) answer the caller immediately with a 202 and keep running for up to 15 minutes. - Scheduled functions run on a cron schedule and have their own, short, limit.
If the limit is configurable for your site, it is set in the Netlify UI or in netlify.toml. Raising it is only worth it if the work is slow because of a legitimately long task. A visitor won't wait a minute for a page anyway.
Why functions get slow
Waiting on a database or API
Most timeouts are a downstream call that hangs, not slow computation. A database that is cold, a third-party API that is degraded, or a connection pool that isn't reused between invocations all look the same from outside. Set explicit timeouts on every outbound call, shorter than the function limit, so you can return a clean error instead of being killed:
// Netlify function (Node 18+): fail fast instead of hanging until the platform kills you
export default async (req) => {
try {
const res = await fetch("https://api.partner.example/data", {
signal: AbortSignal.timeout(8000),
});
return Response.json(await res.json());
} catch (err) {
if (err.name === "TimeoutError") {
return Response.json({ error: "upstream timeout" }, { status: 504 });
}
throw err;
}
};Cold starts
The first request after a quiet period starts a fresh runtime and loads your code. Large dependencies make this worse. Keep the bundle small, import only what you need and create database clients outside the handler so warm invocations reuse them.
Doing too much in one request
Generating a PDF, resizing images, calling five APIs in sequence, or looping over a large list inside one request is the usual way to hit the limit as data grows. Call independent APIs in parallel with Promise.all, and move anything that scales with the amount of data out of the request path.
Move long work out of the request
The reliable fix is to separate "accept the job" from "do the job".
- The browser or your code calls a small function that validates the request, stores a job record and returns at once.
- A background function does the slow work and writes the result.
- The client checks the job status, or you notify the user when it is done.
// netlify/functions/export-background.mjs
// The -background suffix makes Netlify answer 202 straight away and keep this running.
export default async (req) => {
const { reportId } = await req.json();
await buildReport(reportId); // can take minutes
await markReportReady(reportId); // so the page can poll or you can email the user
};The browser calls the background function, gets a 202 immediately, then polls a small status endpoint or waits for an email. Background functions don't return a body to the caller, so the result has to be written somewhere, such as a database row or a blob store.
Do not rely on retries to hide it
Timeouts that aren't the function's fault
- A slow upstream behind a proxy rewrite. If a redirect rule in
netlify.tomlproxies to another origin with status 200, a slow origin can time out the proxy. Test that origin directly. - Response size. Very large payloads fail for a different reason than time. Paginate instead.
- A visitor on a bad connection. If only some users see the error, compare timings from other locations before you blame the code.
Monitor the endpoint, not just the home page
A timeout often hits only one function while the rest of the site loads fine, so a check of the home page misses it. Add an HTTP monitor for the function URL, set the expected status code, and add a response time threshold below your function's limit so you hear about it getting slower before it starts failing. Failures are confirmed from three regions before an alert goes out. The same applies to scheduled functions: have them ping a heartbeat URL at the end so a missed or timed-out run raises an alert.
For the same problem on another platform, see Vercel function timeout (504).
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- HTTP errors · Troubleshootingnginx 502 Bad Gateway: fixing "connect() failed" to PHP-FPM and other upstreamsnginx logs connect() failed (111), (2) or (13) when it can't reach your app. What each errno means, and how to fix PHP-FPM sockets, ports, permissions and SELinux.November 13, 2026 · 7 min read
- HTTP errors · Troubleshooting407 Proxy Authentication Required: what it means and how to fix itA 407 comes from a proxy, not the website. Why it appears in browsers, curl and CI jobs, how it differs from 401, and how to send proxy credentials correctly.November 12, 2026 · 6 min read