Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Next.js server code cannot connect to its own API on 127.0.0.1

ErrorError: connect ECONNREFUSED 127.0.0.1:3003

Short answer

ECONNREFUSED means nothing was listening at that address and port when the server-side fetch ran. In Next.js it is usually a port that does not match the one next dev or next start uses, or a page that fetches its own route during next build while no server is running. Fix the port, or read the data directly.

  • Applies to Next.js 15, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the port in the failing URL with the port the app really listens on, and note whether the error appears in next dev or in next build.

    grep -rn "127.0.0.1\|localhost:" app src pages .env* 2>/dev/null | grep -v node_modules
  2. 2Match what you see, then jump to its fix

    1. 1The error names a port such as 3003 while next dev prints 3000.The URL uses a port the app does not listen onFix
    2. 2The error appears only during next build, with no server running.A page fetches its own route handler while next build runsFix

What does the error look like?

  • Error: connect ECONNREFUSED 127.0.0.1:3003

Cause 1 of 2

The URL uses a port the app does not listen on

1Check

Next.js listens on 3000 by default for next dev and next start. The port changes only with -p, --port or the PORT environment variable.

grep -n "next dev\|next start" package.json

2Fix

Run the app on the port the URL expects, or read the base URL from one environment variable used by both. PORT cannot be set in .env, because the server starts before .env is loaded.

next dev -p 3003
# or
PORT=3003 next dev

3Verify

Request the route from the terminal, then reload the page.

curl -i http://127.0.0.1:3003/api/items

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 2

A page fetches its own route handler while next build runs

1Check

A fetch that runs before any Request-time API is used is made once at build time when the route is prerendered. Nothing serves your route handler during the build.

npx next build 2>&1 | grep -B2 -A6 ECONNREFUSED

2Fix

Skip the HTTP hop: move the data code into a function and call it from both the page and the route handler. If the page must stay dynamic, mark it so it is rendered per request.

// app/items/page.tsx
export const dynamic = 'force-dynamic'

3Verify

Run the build again; it finishes without trying to connect.

npx next build

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Put shared data access in a plain function and call it from both pages and route handlers.
  • Keep one base-URL environment variable instead of hard-coded localhost URLs.
  • Run next build in CI so a build-time fetch failure shows up before deploy.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.