How to Bind a Node App to 0.0.0.0 (Fix nginx 502 Bad Gateway)

Why nginx gets "connection refused"

A reverse proxy and the app it proxies to are separate processes reaching each other over a network interface. When your Node app calls:

server.listen(3000, '127.0.0.1');

it binds to the loopback interface only. 127.0.0.1:3000 is reachable from the same host context, but not from every interface. When nginx (or a sidecar, or a container bridge) tries to open a connection to the upstream, the kernel refuses it because nothing is listening on the interface nginx used. nginx surfaces that refusal as 502 Bad Gateway and logs connect() failed (111: Connection refused) while connecting to upstream.

The app "starts without errors" the whole time, which is why this wastes 20 minutes if you do not check the bind address first.

Step 1: confirm the bind address

Look at what is actually listening, not just whether the process is up:

ss -tlnp | grep :3000

A loopback-only bind looks like this - note the 127.0.0.1:

LISTEN 0 511 127.0.0.1:3000 0.0.0.0:* users:(("node",pid=1842,fd=18))

That single 127.0.0.1 is the whole bug. A correct bind shows 0.0.0.0:3000.

You can prove it further: curl http://localhost:3000/ works (loopback), but the request through curl http://localhost:80/ returns 502 because nginx cannot reach the upstream.

Step 2: bind to all interfaces

Change the listen call in server.js to bind on 0.0.0.0:

const PORT = 3000;
server.listen(PORT, '0.0.0.0', () => {
  console.log(`Server running on port ${PORT}`);
});

Dropping the host argument entirely (server.listen(PORT)) also works, because Node defaults to all interfaces. Being explicit about 0.0.0.0 documents the intent.

Step 3: restart and verify

The process must be restarted for the new bind to take effect:

pkill -f "node server.js"
node server.js > /var/log/node/app.log 2>&1 &

Confirm the new bind, then test through nginx:

ss -tlnp | grep :3000            # now shows 0.0.0.0:3000
curl -s -o /dev/null -w "%{http_code}" http://localhost:80/

The status code is now 200 instead of 502. If nginx still complains, reload it with nginx -s reload so it re-resolves the upstream, and re-check /var/log/nginx/error.log.

127.0.0.1 vs 0.0.0.0

• 127.0.0.1 (loopback) - reachable only from the same host, over the loopback interface. Fine for a local dev script, wrong for anything behind a proxy.
• 0.0.0.0 - listen on every interface the machine has. This is what a service behind nginx, or running in a container, needs so the proxy or bridge network can connect.

This is a top-five deploy-time gotcha for containerized services: the fix is one argument, but you only find it fast if you check ss/netstat before assuming the app is broken.