ERR_CONNECTION_REFUSED on Hosts File Domains: 6 Fixes (2026)

ERR_CONNECTION_REFUSED on a hosts file domain means your computer successfully resolved the domain name to an IP address, but no service is listening on the requested port.

Your hosts file did its job: it mapped the domain to an IP (usually 127.0.0.1). The rejection happens at the network layer because your browser expects a server on port 80 (HTTP) or port 443 (HTTPS), while your development process is running on a custom port (like 3000 or 5173), bound to an incompatible interface, or stopped.

Find your situation: Select your role and stack

Scan the matrix below to identify your role, stack, and exact solution:

Why this error happens (in 30 seconds)

The hosts file has a single responsibility: mapping a hostname to an IP address. It cannot configure ports, protocols, or URL paths.

# Valid entry in /etc/hosts:
127.0.0.1  api.local.test

# Invalid syntaxes (ignored or syntax error):
127.0.0.1:3000 api.local.test
http://127.0.0.1 api.local.test

When you visit http://api.local.test in your browser:

See the hosts file syntax and format guide for formatting rules.

---

Fix 1: Add the missing port number to your URL (Frontend developers)

If your dev server runs on a dedicated port (3000 for Next.js, 5173 for Vite, 8080 for Webpack), your browser will not guess it automatically. You must type the port in the address bar.

• Fails: http://api.local.test (connects to port 80)
• Works: http://api.local.test:3000 (Next.js, Remix, Express)
• Works: http://api.local.test:5173 (Vite, SvelteKit, Astro)
• Works: http://api.local.test:8080 (Webpack, Vue CLI, Spring Boot)

If you want clean domain URLs without typing port numbers every time, jump to Fix 4 to set up a local reverse proxy.

---

Fix 2: Fix Localhost and 0.0.0.0 binding conflicts (Node.js, Vite, Next.js)

Modern frameworks frequently bind to localhost, which operating systems resolve to IPv6 loopback (::1). If your hosts file only contains an IPv4 line:

127.0.0.1 api.local.test

Any browser request to api.local.test sends IPv4 packets to 127.0.0.1. If your dev server only listens on IPv6, the connection is instantly refused.

Solution A: Bind your dev server to 0.0.0.0 (Recommended)

Configuring your server to listen on 0.0.0.0 accepts incoming connections from all local IPv4 network interfaces:

• Vite CLI: vite --host 0.0.0.0
• Vite Config (vite.config.ts):

``typescript export default { server: { host: '0.0.0.0', port: 5173, }, }; ``

• Next.js: next dev -H 0.0.0.0
• Node.js / Express:

``javascript const PORT = process.env.PORT || 3000; app.listen(PORT, '0.0.0.0', () => { console.log(Server running on port ${PORT}); }); ``

Solution B: Add dual-stack IPv4 and IPv6 entries to your hosts file

Add both loopback records to ensure resolution succeeds regardless of whether the browser requests IPv4 or IPv6:

127.0.0.1  api.local.test
::1        api.local.test

Read 0.0.0.0 vs 127.0.0.1 and what is localhost for full details.

---

Fix 3: Expose container ports in Docker and Docker Compose (DevOps & Backend)

Docker containers run in isolated network namespaces. Mapping 127.0.0.1 myapp.test in your host hosts file directs traffic to your host machine, not inside the container. You must publish the container port to the host.

Docker Compose configuration

Add explicit port bindings under the ports key in docker-compose.yml:

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"      # Host port 80 -> Container port 80
      - "443:443"    # Host port 443 -> Container port 443
      - "3000:3000"  # Host port 3000 -> Container port 3000

Docker CLI command

If you start containers with docker run, include the -p flag:

docker run -d -p 80:80 -p 3000:3000 --name my-app my-app-image

See also Docker hosts file management.

---

Fix 4: Set up a local reverse proxy for clean URLs (Caddy or Nginx)

If your goal is to access http://api.local.test or http://dashboard.local.test directly on port 80 without port numbers, run a lightweight local reverse proxy.

Caddy setup (Fastest approach)

```text api.local.test { reverse_proxy 127.0.0.1:3000 }

dashboard.local.test { reverse_proxy 127.0.0.1:5173 } ```

``bash caddy run ``

Caddy listens on ports 80 and 443, routing requests to each respective development server.

---

Fix 5: Inspect active socket listeners (Sysadmins & Debugging)

Verify that your application process is active and bound to the expected port before troubleshooting browser settings.

On macOS and Linux

# Check standard HTTP port 80
sudo lsof -nP -iTCP:80 -sTCP:LISTEN

# Check custom application port (e.g., 3000)
sudo lsof -nP -iTCP:3000 -sTCP:LISTEN

• No output returned: The dev server is stopped, failed to compile, or crashed. Check your IDE terminal.
• Different application name returned: Another process occupies the port. Stop that process or assign a different port to your project.

On Windows (PowerShell as Administrator)

Get-NetTCPConnection -LocalPort 80,3000 -State Listen | Select-Object LocalAddress, LocalPort, OwningProcess

---

Fix 6: Switch from .dev to .test TLD (QA & Local domain testing)

Top-level domains like .dev, .app, and .page are owned by Google and included in the browser HSTS preload list. Chrome and Firefox force HTTPS connections to these domains even on localhost.

If your local server does not have TLS certificates configured on port 443, navigating to myapp.dev results in an immediate ERR_CONNECTION_REFUSED.

• Avoid: myapp.dev, project.app, api.page
• Use instead: myapp.test, project.localhost, api.local.test

The .test and .localhost TLDs are reserved by RFC 2606 specifically for testing and will never trigger mandatory HTTPS.

Read why .test is the best TLD for local development and how to configure local SSL certificates.

---

Advanced troubleshooting and rare edge cases

If your ports, bindings, and Docker configs are verified but ERR_CONNECTION_REFUSED persists:

1. Flush browser socket pools (Chrome and Edge)

Chromium browsers cache failed socket connection states. Even after starting your server, Chrome may keep rejecting connections until the socket pool is cleared.

2. Verify local firewall permissions

Security software may silently drop inbound connections on non-standard ports:

• macOS: Check System Settings > Network > Firewall > Options to ensure your terminal or Node binary is allowed.
• Windows: Check Windows Defender Firewall with Advanced Security for inbound rules blocking Node.js or Docker.

---

Manage local domains cleanly with Sleezr

Managing hosts file entries across multiple stacks, microservices, and staging domains manually is prone to port confusion and syntax mistakes.

Sleezr gives developers and QA teams a visual dashboard to organize domains into toggleable project environments, verify IP bindings, and automatically flush DNS caches without touching the terminal.