Clash Port Already in Use on Startup: Find the Process and Change the Listening Port

Read the error first: identify the conflicting listener

The Clash GUI opens, but the core fails to start and the log shows address already in use. This usually means another listener is already using the address and port Clash is trying to bind. Note the protocol, address, and port in the log, then find the process. Don’t reimport your subscription just because startup failed.

listen tcp 127.0.0.1:7890: bind: address already in use

This is an example error, not a record of a live test. It points to local TCP port 7890; it does not mean the proxy node is unavailable. On Windows, you may see equivalent messages such as “Only one usage of each socket address is normally permitted.” If the log says access denied or reports a permissions error, also check excluded port ranges and security policies rather than treating it as a standard port conflict.

Windows: Find the listening PID and check its executable path

Use PowerShell to check TCP listeners

Right-click Start and open Terminal or Windows PowerShell. Run the command below first. If access is restricted or you need information about processes running under another account, reopen Terminal as an administrator.

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

OwningProcess is the process ID (PID). If the result is 1234, use it to check the process name, path, and startup arguments. Here, 1234 is only an example; replace it with the value from your query.

Get-Process -Id 1234 | Select-Object Id, ProcessName, Path

Get-CimInstance Win32_Process -Filter "ProcessId = 1234" |
  Select-Object ExecutablePath, CommandLine

The executable path and startup arguments are more useful than the process name. Different clients may both run a core named mihomo.exe; the config path in the command line can help identify which client it belongs to. Don’t force-quit a process just because its name contains Clash or mihomo.

Alternative: use Command Prompt

netstat -ano -p tcp | findstr ":7890"
tasklist /FI "PID eq 1234"

With netstat, check the port in the “Local Address” column and confirm the state is LISTENING. findstr only filters text, so it may also match a remote address or a longer port number. A TIME_WAIT entry does not mean a process is currently listening.

No listener found, but the bind error persists

First check whether the client is repeatedly restarting the core, causing the listener to disappear between queries. If the log reports a permissions error, check Windows TCP excluded port ranges from an administrator terminal:

netsh interface ipv4 show excludedportrange protocol=tcp

If the port falls within an excluded range, choose an available port outside that range. Don’t delete system reservations without a clear reason; Hyper-V, containers, or other networking components may rely on them. If the error specifically names an IPv6 address, check the corresponding IPv6 configuration too.

macOS and Linux: distinguish regular processes from background services

macOS: Find the listener with lsof

Open Terminal and find the process listening on TCP port 7890. -nP prevents addresses and ports from being converted to names, making them easier to compare with the log.

sudo lsof -nP -iTCP:7890 -sTCP:LISTEN
ps -p 1234 -o pid,ppid,user,command

Use the PID returned by the first command in the second command. If another proxy client is still running in the menu bar, quit it from its menu, then check again. Some clients keep running after you close their window; a closed window doesn’t mean the core has stopped.

Linux: Check sockets with ss

sudo ss -ltnp 'sport = :7890'
ps -p 1234 -o pid,ppid,user,args

-l means listening, -t selects TCP, -n keeps addresses numeric, and -p shows process information. If your distribution doesn’t include ss, use the macOS command above if lsof is available.

If systemd manages the process, killing it directly may cause it to restart automatically. Run systemctl status 1234 to help identify its service, then stop the confirmed service unit. For a user service, query it with systemctl --user. Don’t guess service names and disable them in bulk.

For a DNS conflict, check UDP instead

The commands above check TCP only. If the log points to UDP port 1053, use the command below, replacing the number to check a different port. TCP and UDP are separate transport protocols, even when they use the same port number; an empty TCP result does not mean UDP is also free.

# macOS or Linux with lsof installed
sudo lsof -nP -iUDP:1053

# Linux
sudo ss -lunp 'sport = :1053'

Identify the cause: duplicate core, another app, or overlapping config

Once you have the process path, choose the right fix. A port conflict usually doesn’t require uninstalling software or changing the node protocol, rule mode, or subscription URL.

1. An old client is still running in the background. For example, one client is using port 7890 for its proxy, and another requests the same port at startup. Keep the client you want to use, quit the other normally, and check whether it launches at startup.
2. A service is running outside the GUI. A manually launched core, system service, or scheduled task may be loading a different config. Identify which process it belongs to, then stop that instance. Otherwise, a service manager may start it again immediately.
3. Another essential app is using the port. If the process has a clear purpose, leave it running and change Clash’s listening port. Don’t terminate a system process or unknown service just to free a port.
4. The same config has overlapping listeners. Check whether port, socks-port, and mixed-port use the same address and port. A mixed listener already accepts both types of request; you don’t need to add a separate listener on the same port.

Check the bind address too. 127.0.0.1:7890 is limited to the local loopback interface, while 0.0.0.0:7890 listens on all IPv4 interfaces; they can conflict. Whether IPv6 [::]:7890 also covers IPv4 depends on the system and socket settings. Listening on all interfaces is not a general-purpose fix—it also makes the proxy accessible over a wider range of connections.

Change the listening port at the source that actually takes effect

Check 7897 first, then change mixed-port

Replace 7890 with 7897 in the lookup commands above and make sure there’s no conflict. If you need to keep two clients running, assign each a different proxy listener. Check other listeners, such as the control API, separately too.

# Fields to check only; this is not a complete config
mixed-port: 7897
allow-lan: false
mode: rule

This example is for a mixed proxy listener used only on the local machine. When merging it into an existing YAML file, edit the existing field instead of appending a second mixed-port entry. If the config already has separate port or socks-port entries, disable them or assign different ports as needed. Don’t replace your entire subscription with these three lines; keep your nodes, proxy groups, and rules.

Which takes precedence: client settings or the subscription file?

Clash refers to a core and its configuration ecosystem; each GUI client has its own menus and override behavior. In your current client’s settings, look for “Port,” “Mixed Port,” or similar, note the original value, then change it. Menu paths vary, so this guide doesn’t treat one client’s settings as universal.

• The client has a port setting: Change it there first, then restart the core as prompted. This setting may override the matching field in your subscription.
• You run the core directly: Edit the config file specified by the startup arguments. Make sure it’s the file currently in use, not another downloaded copy.
• Your subscription updates automatically: Use the client’s persistent override or merge feature. Direct edits to a downloaded subscription file may be overwritten during an update.

Save your changes, restart the core, then check the startup log and actual listeners. Seeing 7897 in the config editor doesn’t mean the running core has switched ports. If the error still mentions 7890, check setting precedence, the config path, and whether you restarted the right instance in addition to checking for another process using the port.

If external-controller is the source of the conflict, change only its control address—for example, from 127.0.0.1:9090 to the confirmed-free 127.0.0.1:9097—and update the dashboard connection settings too. Don’t use the control API as a regular proxy port or expose it to the public internet while troubleshooting.

What to update after changing the port

The core starts successfully on 7897, but the browser still connects to 7890. The result is often that the port error is gone, but websites still won’t load. Check the apps that use the proxy instead of switching nodes again.

On Windows 11, check the address and port under Settings → Network & internet → Proxy → Manual proxy setup. On macOS, check System Settings → Network → your current connection’s Details → Proxies. Menu names may vary by OS version, and a client-managed setting may be rewritten at startup.

In a terminal, HTTPS_PROXY=http://127.0.0.1:7897 means HTTPS destinations are accessed through an HTTP proxy; the local proxy listener itself doesn’t need TLS. If an app uses SOCKS, choose the corresponding protocol. For example, socks5h usually means the proxy resolves the destination hostname; check the app’s documentation for support.

TUN mode uses a virtual network interface to route traffic that matches its routing rules; it does not mean every app uses mixed-port. However, an app with a manual proxy setting left over may still send requests to the old port. Check TUN startup, routing, and proxy listener conflicts separately.

Verify the fix: confirm the listener is back, then test a request

1. Check the log again to confirm the original bind error no longer appears and there are no new conflicts on the control API or DNS ports.
2. Check the new port and confirm the listening process belongs to the client you’re using, not another copy of an old core.
3. Test the listener with a request that explicitly specifies the proxy, ruling out stale system proxy settings.
4. Then visit the target site in a browser and check the client’s connection log and matched rules.

# macOS / Linux
curl -I --proxy http://127.0.0.1:7897 --connect-timeout 5 --max-time 15 https://example.com

# Windows PowerShell: call curl.exe explicitly
curl.exe -I --proxy http://127.0.0.1:7897 --connect-timeout 5 --max-time 15 https://example.com

example.com is a sample test address; replace it with the site you want to check. Receiving a response header from the destination means the request completed the relevant connection steps. If you get Connection refused, check the address, port, and listener first. If the local proxy accepts the connection but you then see a timeout, authentication failure, or upstream connection error, investigate the node, DNS, network connectivity, and rules instead of treating every issue as a port conflict.

The fix is complete when the intended core listens reliably, the system and apps use the new port, and the setting survives a client restart or subscription update. Following the sequence “read the log → find the process → identify what it belongs to → change the active config source → update apps → test a request” helps separate port conflicts from other network issues. For more configuration help, see the Clash configuration guide; for common connection issues, see FAQ.