Fix 'Connection refused' Error in Node.js on Localhost

You're running a Node.js script that tries to fetch data from your own machine — something like fetch('http://localhost:3000/api') — and the terminal spits out Error: connect ECONNREFUSED 127.0.0.1:3000. This happens a lot when you start a backend server in one terminal, then run your client script in another, but forget to actually start the server. Or you started it, but it crashed silently because of a syntax error. I've seen this exact error dozens of times in Express and Next.js projects.

What's actually happening

ECONNREFUSED means your Node.js process tried to open a TCP connection to a port on localhost, and nothing was listening there. The OS responded with "connection refused" — no firewall blocking, no timeout, just a flat-out rejection. The most common cause is that the server process isn't running. Less common but still frequent: the server is running on a different port than you think.

Here's the thing — Node.js doesn't automatically know what port your server uses. You set it explicitly, like app.listen(3000). If you accidentally used 3001 in your server file and 3000 in your client, you'll get this exact error.

The fix, step by step

1. Check if the server is running. Look at your terminal window where you started your Node server. If it shows something like Server listening on port 3000, you're good. If the terminal shows an error stack trace, the server crashed. Scroll up to see what went wrong — usually a missing module or a typo in your code.
2. If the server isn't running, start it. In the server's directory, run npm start or node server.js (whatever your start script is). Wait until it prints the listening message. Don't run the client code until you see that message.
3. If the server is running, verify the port. Look at the listening message. It will say something like Listening on port 3000. Now check your client code — the URL must match that port exactly. If your server uses 3000, your fetch URL should be http://localhost:3000, not 3001.
4. If the port looks right, test the connection manually. Open a new terminal and run curl http://localhost:3000 (replace 3000 with your actual port). If you get a response, the server is healthy and the problem is in your client script. If you get curl: (7) Failed to connect, the server isn't reachable — go back to step 2.
5. Check for port conflicts. Maybe another process is using your server's port. On macOS or Linux, run lsof -i :3000. On Windows, run netstat -ano | findstr :3000. If you see a process there, that's not your Node server — something else grabbed the port. You can either stop that process or change your server to a different port.

What to check if it still fails

If you've done all that and still get ECONNREFUSED, here are three less obvious things:

• Are you using IPv6? Node.js sometimes resolves localhost to ::1 (IPv6) instead of 127.0.0.1 (IPv4). Your server might be listening on IPv4 only. Try using http://127.0.0.1:3000 directly in your client code. It's a quick test that saves you a headache.
• Did your server crash after starting? Some servers start fine, then crash when they try to connect to a database or another service. Check the server terminal for any error messages after the listening message. If it crashed, you'll see a stack trace — fix that and restart.
• Is your server bound to a specific host? If you wrote app.listen(3000, '192.168.1.10'), it won't accept connections on localhost. Change it to app.listen(3000) or app.listen(3000, '127.0.0.1') to accept local connections.

The real fix is almost always that the server isn't running when the client tries to connect. But when it is running, the port mismatch is the usual suspect. Take a breath, check those two things first, and you'll save yourself an hour of debugging.

If you're using a framework like Express, you can add a log line right after app.listen to print the exact URL you're serving. It's a small habit that prevents this error entirely in the future.

Remember, ECONNREFUSED is your friend — it means your machine is up and talking. It's just that no one's home on that port. Find the right port or start the server, and you're done.