Back to blog

How to Fix Failed to Load Resource net ERR CONNECTION REFUSED

When connecting frontend client applications (like React or Vue running on localhost:3000) to local backend APIs, one of the most frustrating errors in Chrome DevTools is: "Failed to load resource: net::ERR_CONNECTION_REFUSED".

This error means the browser attempted to connect to a target server, but the computer hosting the target port actively rejected the network request. No handshake took place, and no response was returned.

In this guide, we will analyze what triggers connection refused errors, diagnose listening ports, and configure API configurations to restore access.

What Triggers ERR_CONNECTION_REFUSED?

A connection refusal is a network-level TCP handshake failure. Unlike a 404 Not Found or 500 Internal Server Error (which are HTTP responses sent by a running server), ERR_CONNECTION_REFUSED indicates that no server is listening on the target IP address and port.

The browser knocks on the door, and the operating system's network stack responds with a RST (Reset) packet, terminating the connection immediately.

Step 1: Verify the Backend Server is Actually Running

It sounds simple, but the most common cause is that your backend server crashed or was never launched in your terminal.

  • The Check: Open your terminal and check the status of your Node.js, Python, or Docker backend process. If it crashed due to a database exception or code syntax bug, the target port will close.
  • The Fix: Restart the backend daemon and watch for compiling errors. Try accessing the API endpoint directly from your browser search bar (e.g., http://localhost:5000/api/health).

Step 2: Check for Port Mismatches

If your backend is running but you still receive connection refusal warnings, the frontend might be hitting the wrong port number.

  • Compare your frontend API base URL setup against the backend's listening port:
    • Backend configuration: app.listen(5000)
    • Frontend API call: fetch('http://localhost:8080/users')

Ensure the ports match exactly. If you are using a proxy configuration (such as Vite's server.proxy or Webpack's devServer.proxy), verify that the target address points to the correct backend port.

Step 3: Localhost Binding Pitfalls (127.0.0.1 vs. 0.0.0.0)

If you are developing inside a Docker container, virtual machine, or testing on a physical mobile device connected to your local Wi-Fi, binding your backend to 127.0.0.1 (loopback interface) will cause connection refusals.

  • 127.0.0.1 (localhost): Tells the operating system to only accept connections originating from the same local machine. If a container or network device attempts to connect, the host rejects it.
  • 0.0.0.0 (all interfaces): Tells the system to listen on all available network cards, allowing external devices, virtual machines, and docker bridges to connect.

The Fix: Update Backend Bindings

  • Node.js Express:
// Change this:
app.listen(5000, '127.0.0.1');
// To this:
app.listen(5000, '0.0.0.0');
  • FastAPI (Uvicorn):
# Launch binding to all interfaces
uvicorn main:app --host 0.0.0.0 --port 5000

Step 4: Verify System Firewall Blocks

Sometimes, local security tools or the built-in system firewall (Windows Defender Firewall or macOS Pfctl) block inbound traffic on specific development ports (e.g., 5000 or 8080).

To test if a port is open and reachable from your command line:

  • macOS / Linux:
nc -zv localhost 5000
# Connection to localhost port 5000 [tcp/xmltec-xmlmail] succeeded!
  • Windows (PowerShell):
Test-NetConnection -ComputerName localhost -Port 5000
# TcpTestSucceeded : True

If the connection test returns a failure status, configure your operating system's firewall setting to allow incoming TCP traffic on that developer port.

Conclusion

The net::ERR_CONNECTION_REFUSED error occurs when a request target fails to host an active listening server. To resolve it, verify your backend console is running without compilation crashes, match port declarations between client and server configuration environments, configure server hosts to bind to 0.0.0.0 when communicating across container networks, and check system firewalls to ensure development ports are accessible.