next build: fetch failed ECONNREFUSED (build-time API) Next.js Origin: On your device OSI layer 4 · Transport Last updated 5 Nov 2026

Next.js: Error occurred prerendering page "/blog" TypeError: fetch failed { cause: Error: connect ECONNREFUSED 127.0.0.1:3000 }

During next build a page tried to fetch data from a server (often your own app or an API) that isn't running yet.

Exact message you may see Error occurred prerendering page "/blog". TypeError: fetch failed[cause]: Error: connect ECONNREFUSED 127.0.0.1:3000 next buildError occurred prerendering page TypeError: fetch failed ECONNREFUSEDExport encountered errors on following paths ECONNREFUSEDnext build fetch failed ECONNREFUSED
Seen on: Next.js Node.js

Meaning

Static generation runs at build time, when localhost:3000 doesn't exist. Fetch from the real data source (DB/CMS/public API) or make the page dynamic (export const dynamic = 'force-dynamic'). In CI, start required services first or provide the environment variables.

Common causes

  • Pre-render fetching http://localhost:3000/api/...
  • API/CMS not reachable from the build environment
  • Missing environment variables at build (URL undefined)
  • Docker build without network access to the DB
  • Rate limits/firewall during build

⚡ Quick fix

  1. Call the data function directly instead of fetching your own API
  2. export const dynamic = "force-dynamic" to skip prerendering
  3. Provide env vars and network access in CI

Detailed fix by platform

Next.js

  1. export const dynamic = "force-dynamic"; // render at request time

How to diagnose

  1. Target — localhost or external?
  2. Build — Network available?
  3. Env — Variables set?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: On your device. Errors that are often confused with or caused by this one (click to open):

_next/image 400 / upstream image response failed — Next.js: ⨯ upstream image response failed for https://example.com/a.jpg 404 / url parameter is not allowed (Next.js)_next/image 400 / ups…'sharp' is required to be installed in standalone mode — Next.js: Error: 'sharp' is required to be installed in standalone mode for the image optimization to function correctly (Next.js)'sharp' is required t…[Vue warn]: Component is missing template or render function — Vue: [Vue warn]: Component is missing template or render function. (Vue)[Vue warn]: Component…Body exceeded 1 MB limit (Server Actions) — Next.js: Error: Body exceeded 1 MB limit. To configure the body size limit for Server Actions, see: https://nextjs.org/docs/app/api-reference/next-config-js/serverActions#bodysizelimit (Next.js)Body exceeded 1 MB li…Component provided template option but runtime compilation is not supported — Vue: [Vue warn]: Component provided template option but runtime compilation is not supported in this build of Vue. Configure your bundler to alias "vue" to "vue/dist/vue.esm-bundler.js" (Vue)Component provided te…Conflicting app and page file was found — Next.js: ⨯ Conflicting app and page file was found, please remove the conflicting files to continue: "pages/index.tsx" - "app/page.tsx" (Next.js)Conflicting app and p…CORS error calling Next.js API route / route handler — Browser: Access to fetch at 'https://api.example.com/api/data' from origin 'https://app.example.com' has been blocked by CORS policy (Next.js route handler) (Next.js)CORS error calling Ne…Could not find a production build in the '.next' directory — Next.js: Error: Could not find a production build in the '.next' directory. Try building your app with 'next build' before starting the production server (Next.js)Could not find a prod…next buil…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.