GET http://localhost:3000/ net::ERR_CONNECTION_REFUSED

Error: connect ECONNREFUSED 127.0.0.1:3000

Your code is trying to connect to a server that isn’t accepting connections on that port. The request reaches your machine, but nothing is listening.

Fix 1: Is the Server Running?

The most common cause — the server isn’t started.

# Check if anything is listening on port 3000
lsof -i :3000           # Mac/Linux
netstat -tlnp | grep 3000  # Linux

If nothing shows up, start your server:

npm run dev
python manage.py runserver
docker compose up

Fix 2: Wrong Port

Your app is running on a different port than you’re connecting to.

# Check what ports are in use
lsof -i -P | grep LISTEN    # Mac
ss -tlnp                     # Linux

Common mismatches:

• App runs on 3001, you’re hitting 3000
• App runs on 8080, you’re hitting 80
• .env says one port, code uses another

Fix 3: Binding to Wrong Address

Your server might be listening on 127.0.0.1 but you’re connecting from a different interface.

// ❌ Only accessible from localhost
app.listen(3000, '127.0.0.1');

// ✅ Accessible from any interface
app.listen(3000, '0.0.0.0');

This is especially common with Docker — a server inside a container must bind to 0.0.0.0, not 127.0.0.1.

Fix 4: Docker Networking

Inside Docker, localhost means the container itself, not your host machine.

# ❌ Your app tries to reach the database at localhost
DATABASE_URL=postgresql://localhost:5432/mydb

# ✅ Use the Docker service name
DATABASE_URL=postgresql://db:5432/mydb

Container → Host: Use host.docker.internal instead of localhost:

http://host.docker.internal:3000

Container → Container: Use the service name from docker-compose.yml:

services:
  web:
    depends_on: [db]
    environment:
      DB_HOST: db    # ← service name, not localhost
  db:
    image: postgres

Fix 5: Firewall Blocking the Port

# Mac: check if firewall is on
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Linux: check iptables
sudo iptables -L -n | grep 3000

# Allow a port (Linux)
sudo ufw allow 3000

Fix 6: Server Crashed on Startup

The server started but immediately crashed. Check the logs:

# Node.js
npm run dev 2>&1 | head -50

# Docker
docker logs <container-name>

# Check for port conflicts
lsof -i :3000

Common crash causes:

• Missing environment variables
• Database connection failed
• Port already in use (see Docker port fix)
• Syntax error in config

Debugging Checklist

# 1. Is anything listening on the port?
lsof -i :3000

# 2. Can you reach it with curl?
curl -v http://localhost:3000

# 3. Is it a DNS issue? Try the IP directly
curl -v http://127.0.0.1:3000

# 4. Is the server binding to the right address?
# Check your server config for 127.0.0.1 vs 0.0.0.0

# 5. Is a firewall blocking it?
sudo lsof -i :3000