Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

The React dev server cannot proxy a request to the backend (ECONNREFUSED)

ErrorCould not proxy request /pusher/auth from localhost:3000 to http://localhost:5000

Short answer

ECONNREFUSED means nothing accepted the connection at the proxy target. The backend may not be running, the port may differ from the proxy setting, or localhost resolves to an IPv6 address the backend does not listen on. Start the backend first, then use one explicit address and port in the proxy setting.

  • Applies to Node.js 22, Vite 7, react-scripts 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the backend directly, without the dev server. If this fails, the proxy is fine and the backend is the problem.

    curl -i http://127.0.0.1:5000/
  2. 2Match what you see, then jump to its fix

    1. 1curl to the backend port is refused too.The backend is not running, or runs on another portFix
    2. 2The backend works on 127.0.0.1 but is refused through localhost.localhost resolves to an address the backend does not listen onFix
    3. 3The project uses Vite and the error shows a path that the backend does not serve.Vite proxy entry has the wrong target or pathFix

What does the error look like?

  • Could not proxy request /pusher/auth from localhost:3000 to http://localhost:5000
  • (ECONNREFUSED)

Cause 1 of 3

The backend is not running, or runs on another port

1Check

Check what the proxy target is, and what is listening.

grep -n "proxy" package.json
lsof -iTCP -sTCP:LISTEN -P | grep node

2Fix

Start the backend, and make the port in the proxy setting the one it prints. Restart the dev server after changing package.json.

// package.json (Create React App)
"proxy": "http://localhost:5000"

3Verify

Repeat the failing request from the app and read the dev server output.

curl -i http://127.0.0.1:5000/

Confirmed by create-react-app.dev

Did this fix it?

Cause 2 of 3

localhost resolves to an address the backend does not listen on

1Check

Since Node.js 17 the default DNS result order is verbatim, so addresses are not reordered and localhost can resolve to ::1 first. A backend bound to IPv4 only refuses it.

curl -i http://127.0.0.1:5000/
curl -i "http://[::1]:5000/"

2Fix

Point the proxy at the explicit IPv4 address, so name resolution cannot pick a different one.

"proxy": "http://127.0.0.1:5000"

3Verify

Restart the dev server and repeat the request.

npm start

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

Vite proxy entry has the wrong target or path

1Check

In Vite the proxy lives in vite.config. Requests whose path starts with the key go to the target; a rewrite changes the path before forwarding.

grep -n "proxy" -A8 vite.config.*

2Fix

Set the target to the backend's real address and use rewrite when the backend does not expect the prefix.

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://127.0.0.1:5000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, ''),
      },
    },
  },
})

3Verify

Restart Vite and call the route through the dev server.

curl -i http://localhost:5173/api/health

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Put the backend port in one env file and read it in both the server and the proxy setting.
  • Use 127.0.0.1 in dev configs so name resolution cannot change the target.
  • Start the backend before the dev server in your dev script.

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.