MegalaniaBlog
  1. Blog
  2. How to fix
  3. Node fetch timeout

Node fetch timeout: 300 seconds, then fetch failed

Node's fetch has no timeout option. It waited 301 seconds, then failed with UND_ERR_HEADERS_TIMEOUT. AbortSignal.timeout, a retry loop, and our API.

Jordan HayesDeveloper Relations
2 min read
How to fix
A request arrow leaves a terminal card and stops at a stopwatch. Behind it a server card sits with a spinning wait icon. A second arrow goes around, through a small retry loop, and reaches a page that reads 200.

The short answer: Node's built-in fetch has no timeout option. Against a server that never sent its headers, it waited 301.6 seconds, then rejected with TypeError: fetch failed. The reason is in err.cause: UND_ERR_HEADERS_TIMEOUT, undici's 5-minute limit for response headers. Pass signal: AbortSignal.timeout(ms) on every call to set your own limit. When it runs out, the error is a DOMException named TimeoutError, not a TypeError, so branch on err.name. When a page is slow because it needs a browser, send it to our API, and a call that runs out of time costs nothing.

What Node fetch does on a slow server

Start a listener in one terminal with nc -lk 8799. It takes each connection and never answers, like a server that hangs. Run this in a second terminal:

Terminal 2
node -e 'const t = Date.now(); fetch("http://127.0.0.1:8799/").catch((e) => console.log(e.name, "|", e.message, "|", e.cause?.code, "| after", ((Date.now() - t) / 1000).toFixed(1), "s"))'
Output
TypeError | fetch failed | UND_ERR_HEADERS_TIMEOUT | after 301.6 s
  • Five minutes and a generic error. err.message is only fetch failed. The useful part, UND_ERR_HEADERS_TIMEOUT, is on err.cause.code.
  • That limit is undici's headersTimeout, 300 seconds. Once headers arrive, a second limit, bodyTimeout, covers the wait between chunks of the body.
  • A script that loops over pages with no signal can spend 5 minutes on every server that hangs.

How Node fetch reports a timeout

Our test store answers fast, so give it a limit too short to meet. The error is the same one a slow site gives you:

seen.mjs
try {
  await fetch("https://lab.megalania.io/product/alpine-down-parka/", { signal: AbortSignal.timeout(50) });
} catch (err) {
  console.log(err.name, "|", err.message, "| a DOMException:", err instanceof DOMException);
}
Output
TimeoutError | The operation was aborted due to timeout | a DOMException: true
  • AbortSignal.timeout(50) gave TimeoutError, a DOMException. A plain AbortController you abort yourself gives AbortError instead.
  • The signal covers the whole call, body included, as long as you read the body before it fires.

The free fix: timeouts and retries

Set a limit on every request, and retry a few times with a pause. This fixes servers that are slow now and then:

fix.mjs
async function get(url, tries = 3) {
  for (let n = 1; ; n++) {
    try {
      const res = await fetch(url, { signal: AbortSignal.timeout(20000) });
      return { res, html: await res.text() };
    } catch (err) {
      if (err.name !== "TimeoutError" || n === tries) throw err;
      await new Promise((r) => setTimeout(r, 2000 * n));
    }
  }
}

const { res, html } = await get("https://lab.megalania.io/product/alpine-down-parka/");
console.log(res.status, "|", html.match(/<h1[^>]*>(.*?)<\/h1>/)[1], "|", html.length, "characters");
Output
200 | Alpine Down Parka | 101475 characters
  • await res.text() is inside the try, so a body that stalls is a timeout too, and gets retried.
  • Make a new AbortSignal.timeout for each try. A signal that already fired stays fired.
Free beta, by invite76,000 credits for 30 days, no card. Apply, and we email your invite.Apply for the beta

The fix that climbs: our API

Send the page to our API instead. We fetch it, run a real Chrome when you ask, and an answer that runs out of time costs nothing:

fetch.mjs
// Run: MEG_API_KEY=YOUR_KEY node fetch.mjs https://lab.megalania.io/product/alpine-down-parka/
const [url, ...extra] = process.argv.slice(2);
const res = await fetch("https://get.megalania.io/v1", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEG_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ url, response_types: "markdown", ...Object.fromEntries(extra.map((a) => a.split(/=(.*)/s).slice(0, 2))) }),
  signal: AbortSignal.timeout(100000),
});
const text = await res.text();
console.log(res.status, res.headers.get("x-route") ?? "-", "credits", res.headers.get("x-credits-charged") ?? 0, "|", text.length, "characters");
console.log(text.slice(0, 130));
Output
200 http/datacenter credits 1 | 2806 characters
[![Alpine Down Parka](https://lab.megalania.io/wp-content/uploads/gibber/alpine-down-parka-416x628.webp)](https://lab.megalania.io
  • The product page was 101,475 characters of HTML from Node, and 2,806 characters of Markdown from us.
  • AbortSignal.timeout(100000) on our call is longer than our limit of 90 seconds a page.

The same call on a page whose list never finishes loading, with a 20-second limit:

Terminal
MEG_API_KEY=YOUR_KEY node fetch.mjs https://lab.megalania.io/new-arrivals/ engine=browser actions=wait_for:#item-99 timeout=20
Output
422 - credits 0 | 350 characters
{"error":{"code":"action_failed","field":"actions","message":"actions entry 0 could not run: no visible element matched its select
  • No 5-minute wait here. Our Chrome gave up on #item-99 when the time for actions ran out, and we answered with a short 422 action_failed.
  • 350 characters of JSON with a message that says what to change. No charge header, so the script printed 0.

One honest note: our test store is fast, so these runs show a short limit or a page that never gets ready, not a slow site. On a slow site, the call is the same; the price depends on the route that worked, and our MCP tool check_site tells you that price for free.

What it costs

What we ranRouteCredits
A product page as Markdownh:dc1
A page that never got ready, in the browserc:dc0
The nc run, seen.mjs and fix.mjs, straight from Nodenone0

Every rule is in Credits. Plans are on the pricing page.

How we measured: The built-in fetch (undici) in Node 24.21, one Linux server, 17 Nov 2026. nc -lk 8799 (OpenBSD netcat) as a server that never answers; that run took 5 minutes. Our test store for the short limit and for fix.mjs. Our API on our dev cluster for fetch.mjs, against the same store on our dev domain. The outputs are copied from those runs.

Limits

  • Public pages only. We do not log in, and we do not solve CAPTCHAs. When a page needs either, we stop and say so, for free.
  • A page built by JavaScript needs engine=browser. It costs more. See How to scrape JavaScript-rendered pages.
  • Slow can mean slow down. A site that answers slowly may be under load. Keep your rate low, fetch public pages only, and follow the site's terms and robots.txt.

What to do when a site answers 429 instead is in 429 Too Many Requests when scraping.