Next.js server code cannot connect to its own API on 127.0.0.1
Error: connect ECONNREFUSED 127.0.0.1:3003Short 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.
Fix it fast
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_modules2Match what you see, then jump to its fix
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.json2Fix
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 dev3Verify
Request the route from the terminal, then reload the page.
curl -i http://127.0.0.1:3003/api/itemsConfirmed by nextjs.org
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 ECONNREFUSED2Fix
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 buildConfirmed by nextjs.org
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
Web apps
TypeError: fetch failed in a Next.js Server Component or route handler
TypeError: fetch failed
TypeError: fetch failed is a wrapper.
3 causes, each with a fixBack end
create-next-app keeps creating a TypeScript project
Would you like to use TypeScript? No / Yes
create-next-app now makes a TypeScript project by default.
2 causes, each with a fixBack end
Show a custom sign-in error in NextAuth without leaving the page
http://localhost:3000/api/auth/error?error=...
By default a failed NextAuth credentials sign-in navigates to the error page with the message in the URL.
3 causes, each with a fixBack end
Request body is rejected as too large in Next.js (1 MB default)
413 Payload Too Large
Next.js limits request bodies to 1 MB by default, in both Pages Router API routes and Server Actions.
3 causes, each with a fixBack end
next build stops with: Failed to collect page data for a route
Error: Failed to collect page data for /dashboard
Failed to collect page data for a route is the last line of a failed build, not the cause.
3 causes, each with a fixBack end
TypeError: Failed to parse URL when a Next.js server fetches its own API
TypeError: Failed to parse URL from undefined/api/test
Server code has no page address, so fetch('/api/test') cannot be turned into a full URL and throws Failed to parse URL.
3 causes, each with a fix