Next.js "TypeError: fetch failed" during static generation in CI

By Daniel Zoghalchali·Latchkey

Server components, generateStaticParams, and generateMetadata can fetch data while next build prerenders pages. If that request fails (unreachable host, no DNS, or a service that is not running in CI), the build throws "TypeError: fetch failed".

What this error means

next build aborts with "TypeError: fetch failed" and a cause such as ECONNREFUSED or ENOTFOUND, often pointing at a localhost or internal URL that exists in production but not on the runner.

Error occurred prerendering page "/products".
TypeError: fetch failed
  [cause]: Error: connect ECONNREFUSED 127.0.0.1:3000

Common causes

The fetched host is unreachable from CI

A request to localhost, an internal service, or a host requiring VPN cannot be reached during the build, so fetch rejects.

A transient DNS or connection failure

A momentary network error makes a single build-time fetch fail and abort prerendering.

How to fix it

Make build-time data reachable or move it to runtime

1. Point build-time fetches at a host reachable from the runner, or provide the data another way.
2. For data that only exists at runtime, render the route dynamically instead of at build.
3. Re-run next build.

// render at request time instead of build time
export const dynamic = 'force-dynamic'

Handle fetch failures so the build does not crash

Check the response and provide a fallback so an unreachable upstream does not abort the build.

const res = await fetch(url).catch(() => null)
if (!res || !res.ok) return { products: [] }

How to prevent it

• Avoid fetching internal-only hosts during the build.
• Render request-time data dynamically rather than at build.
• Add fallbacks for build-time fetches and retry transient failures.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation