Connection Refused to WSL(Linux) Host - Troubleshooting Guide

Resolving a connection refused error to your WSL Linux host typically involves verifying that the service is actively listening on the correct interface, ensuring Windows Firewall rules permit inbound traffic, and confirming that the WSL network adapter IP address has not changed. Most issues stem from services binding only to localhost or missing firewall exceptions for the private network profile.

Understanding the WSL2 Network Architecture

WSL2 operates as a lightweight virtual machine rather than a native container. This architectural shift means it utilizes Hyper-V networking, which assigns the Linux instance a dynamic IP address within a NAT (Network Address Translation) environment. Unlike WSL1, where Linux components ran directly on the Windows kernel, WSL2 requires explicit port forwarding or proper network configuration to allow external connections from the Windows host or other devices on your local network. When you attempt to connect to a service running inside WSL2 using localhost, Windows automatically forwards that traffic to the current IP address of the WSL2 VM. However, if the service inside Linux is not bound to all interfaces, or if the firewall blocks the entry point, the connection will be refused. It is crucial to distinguish between connecting from Windows versus connecting from another machine. Connecting from Windows usually works via localhost due to automatic port forwarding. Connecting from another device requires knowing the specific IP address of the WSL2 adapter and ensuring that device can route to it. If you are seeing "Connection Refused," it generally means the TCP handshake reached the target but was rejected by the application or the operating system's security layer, rather than being dropped entirely due to a routing failure. For deeper insights into related networking quirks, see our guide on Troubleshooting SSH WSL Machine: Can't Connect to Localhost.

Step 1: Verify the Service is Listening Correctly

The most common cause of this error is the application inside WSL2 binding strictly to 127.0.0.1 instead of 0.0.0.0. When a service binds to 127.0.0.1, it only accepts connections originating from within the same network stack. Since WSL2 has its own loopback interface, 127.0.0.1 inside Linux does not refer to 127.0.0.1 in Windows. Therefore, external requests forwarded via NAT may be rejected if the service ignores non-loopback addresses. To diagnose this, open your WSL terminal and use the netstat or ss command to check the listen state. Run the following command to see what addresses your service is listening on:

sudo ss -tlnp | grep :PORT_NUMBER

Replace :PORT_NUMBER with the actual port your application uses (e.g., :80 for HTTP or :22 for SSH). Look at the Local Address:Port column. If you see 127.0.0.1:PORT, the service is misconfigured for external access. You must modify your application’s configuration file to bind to 0.0.0.0 or :: (for IPv6). For example, in Nginx, you would change listen 80; to ensure it doesn't restrict to localhost. In Node.js applications, ensure the host parameter is set to '0.0.0.0' when calling app.listen(). After changing the binding, restart the service and test the connection again.

Step 2: Check Windows Firewall Rules

Even if the service is listening correctly, Windows Firewall may block incoming connections. By default, Windows often treats new network adapters as "Public" networks, which have strict inbound blocking rules. The WSL2 virtual Ethernet adapter might be classified incorrectly, causing the firewall to drop packets before they reach the forwarding logic. You can verify the network profile type by opening PowerShell as Administrator and running:

Get-NetConnectionProfile

If the WSL2 adapter shows a NetworkCategory of Public, you should change it to Private to allow trusted local connections. Use the following command, replacing NAME with the name of the WSL adapter (often something like vEthernet (WSL)):

Set-NetConnectionProfile -Name "vEthernet (WSL)" -NetworkCategory Private

Additionally, ensure that an inbound rule exists for the specific port you are trying to access. You can create a rule via the GUI or PowerShell. For PowerShell, run:

New-NetFirewallRule -DisplayName "Allow WSL Port" -Direction Inbound -LocalPort PORT_NUMBER -Protocol TCP -Action Allow

This step is critical because many users assume that since they can ping the WSL IP, the firewall is open. Ping uses ICMP, which might be allowed while TCP ports remain blocked. If you suspect permission issues with system resources, review how we handle WSL Distributions Stopping Computer Starts - Docker Desktop Error: Access Denied.

Step 3: Confirm the WSL2 IP Address

Because WSL2 IPs are dynamic, they can change every time the distribution stops and starts. Relying on a hardcoded IP address from a previous session will lead to connection failures. To find the current IP, run this command inside your WSL terminal:

hostname -I

This returns one or more IP addresses assigned to the VM. Try connecting to this specific IP address from your Windows host using telnet or Test-NetConnection in PowerShell:

Test-NetConnection -ComputerName WSL_IP_ADDRESS -Port PORT_NUMBER

If this fails, the issue is likely within the Linux firewall (iptables/nftables) or the application itself. If it succeeds, the problem is isolated to how you were attempting to connect previously (e.g., using an outdated IP). Note that accessing this IP from outside your local machine requires port forwarding on your physical router, which is beyond the scope of local troubleshooting.

Step 4: Inspect Linux Internal Firewalls

Linux distributions come with their own firewall utilities, such as ufw (Uncomplicated Firewall) or iptables. Even if Windows allows the traffic through, the internal Linux firewall might reject it. Check the status of UFW by running:

sudo ufw status

If the status is active, ensure that the port you need is listed as ALLOWED. If it is not, add a rule:

sudo ufw allow PORT_NUMBER/tcp

For systems using iptables directly, you can list input rules with sudo iptables -L -n. Look for any DROP or REJECT statements affecting your port. If you find restrictive rules, you may need to flush them or adjust the chain policies. Remember that modifying these settings requires root privileges, so always prefix commands with sudo. If you encounter permission errors during these steps, refer to our article on Lost Sudo Privileges in WSL Ubuntu: Re-enabling Sudo Access.

Frequently Asked Questions

Why does localhost work but the IP address does not?

This usually happens because Windows automatically forwards localhost traffic to the WSL2 VM via NAT, bypassing some network checks. Direct IP access goes through the standard network stack, which may be blocked by firewalls or require different binding configurations. Ensure your service binds to 0.0.0.0 to accept direct IP connections.

Can I make the WSL2 IP address static?

WSL2 does not natively support static IP assignment for the virtual adapter. However, you can automate the retrieval of the current IP using scripts or aliases in your bash profile. Alternatively, consider using port forwarding rules in .wslconfig to map specific host ports to container ports consistently.

Does Docker Desktop affect WSL2 networking?

Yes, Docker Desktop integrates deeply with WSL2 and can interfere with network adapters and permissions. If you recently installed Docker and started facing connection issues, check if Docker is monopolizing the network bridge. Reviewing common access denied errors in Docker can help isolate these conflicts.

How do I troubleshoot if the service is running but still refusing connections?

First, verify the process is actually listening on the expected port using netstat or ss. Second, check both Windows and Linux firewalls for blocking rules. Third, ensure the application is not configured to reject connections from remote hosts or specific IP ranges in its config files.

Is it safe to disable the Windows Firewall for WSL?

Disabling the entire Windows Firewall is not recommended due to security risks. Instead, create specific inbound rules for the ports your WSL services use. This allows necessary traffic while keeping the rest of your system protected against unauthorized access attempts.