Fix dsh web port conflicts: occupied, denied, bad host
DeepSeek Harness port problems look like one symptom, but the error codes split into three classes with different fixes: address already in use, permission denied or a reserved range, and an address the host does not own. Classify first, then decide between changing ports and handling the holder, then confirm the bind address. Each entry has its own port, so fix only the one that failed.
Three classes of "port unavailable" in DeepSeek Harness
Bottom line: the error code dictates the fix, and misclassifying wastes the effort.
| Class | Typical message | Cause | Fix |
|---|---|---|---|
| Port occupied | address already in use | Another process bound it | Change port or stop the holder |
| Permission or reserved range | permission denied | Low port, reserved range, unprivileged user | Move to a high port |
| Address unavailable | cannot bind to address | The bound IP does not exist or is down | Correct the bind address |
- Do not skip classification. If no error code is visible, read the last lines of startup output — they usually name the class.
- All three appear as "will not start," so "try another port" only addresses the first and part of the second.
Option A: change the port (fastest)
Bottom line: changing ports is usually faster than hunting the holder, unless that port is already referenced in proxy configuration or documentation.
- Confirm the candidate is free (macOS and Linux):
lsof -nP -iTCP:3180 -sTCP:LISTEN # expected: no output means the port is free
- Start with the new port (flag names per dsh web --help):
dsh web --host 0.0.0.0 --port 3180
# expected: starts and prints the listen address
- Update every reference — proxy configuration, documentation, bookmarks. One missed reference looks like "the service is fine but unreachable."
- Verify: curl -I http://127.0.0.1:3180 responds locally, then check through the proxy or another device.
- Port selection advice: avoid low ports (privileges) and common service ports (collisions); pick an uncommon value between 3000 and 9000.
Option B: find the holder and handle it (when you must keep the port)
Bottom line: investigate only when the port is pinned by external references. Order: identify the process, judge whether it can stop, then decide.
- Identify the holder:
# macOS / Linux
lsof -nP -iTCP:3080 -sTCP:LISTEN
# Windows (PowerShell)
# Get-NetTCPConnection -LocalPort 3080 | Select-Object OwningProcess
- Judge whether it can stop: a leftover DeepSeek Harness process from a previous run is safe to stop; another service deserves an impact assessment first.
ps -ef | grep -i dsh | grep -v grep # confirm whether it is a leftover DSH process
- Stop the leftover and start again, preferring a normal termination signal over force-killing.
- Verify: restart and confirm the port now belongs to your process.
- Ask why a leftover existed: an undeleted container, an abnormal exit, or multiple entry points at once. These three cover most cases.
Option C: keep DeepSeek Harness ports out of reserved ranges
Bottom line: on Windows, "nobody holds it but it will not bind" usually means the port is in a dynamic or reserved range. Fix it by pinning a port outside those ranges.
- Inspect the reserved range with the system command documented by Microsoft (exact command varies by version).
- Pin the dsh web port outside those ranges in a startup script instead of letting it vary.
- Containers add another layer: a non-root container user also cannot bind low ports, so standardize on high ports.
- Document the port: when sharing, the port is configuration; writing it down prevents everyone picking a different one.
- Verify: reboot and start again — reserved-range failures reproduce most reliably after a restart.
Port relationships across DeepSeek Harness entry points
Bottom line: each entry has its own port, conflicts happen only on the same port, and fixing the failing one is enough.
| Entry | Port behavior | Common conflict |
|---|---|---|
| CLI | Usually no long-lived listening port | Occasional contention with background jobs |
| Desktop app | Own service port (fixed or dynamic) | Collides with dsh web |
| dsh web | Determined by startup flags (default or custom) | Collides with the above or third-party services |
- Identify which entry failed and handle only that one.
- Never configure two entries on the same port.
- With a proxy present: the proxy listens on one port and dsh web on another; they cannot match (see dsh web behind a reverse proxy).
- In containers: host port and container port are distinct; a wrong mapping also looks like a conflict or unreachable service (see installing DeepSeek Harness in Docker).
Three-step diagnosis for DeepSeek Harness port failures
Bottom line: classify, check the holder, verify the bind address. These three always produce a conclusion.
- Classify: read the error code against the three classes above.
- Check the holder: lsof on POSIX or Get-NetTCPConnection on Windows.
- Verify the address: ipconfig or ip addr to confirm the bound address exists locally (a wrong IP yields address unavailable).
- Decision table:
| Observation | Conclusion | Next step |
|---|---|---|
| In use plus a process in lsof | Occupied | Change port or stop the holder |
| Permission denied and port under 1024 | Privileges | Move to a high port |
| Permission denied and port in reserved range | Reserved range | Move outside the range |
| Address unavailable | Wrong bind address | Correct the address |
- Verify the fix by restarting and accessing the service, not just by the absence of startup errors.
DSH plugin troubleshooting around port problems
Bottom line: port issues are unrelated to plugins. Rule them out first, then investigate plugins, and save half the time.
- Service will not start is a port-layer problem. Service starts but plugin features fail is a plugin-layer problem (see DSH plugin conflicts).
- Do not touch authentication settings: port failures have nothing to do with auth, and mixing the two obscures the diagnosis.
- In containers, separate host port from container port — wrong mappings get misreported as conflicts.
- Document the port when sharing, and keep a spare.
- Note failures that only appear after a reboot: they usually involve reserved ranges or services grabbing the port at startup.
- Repair status, stated honestly: the three-class classification and fixes summarize general operating system behavior. DeepSeek Harness default ports and flag names should be confirmed with dsh web --help, and Windows reserved-range commands should follow Microsoft's documentation.
If only port 3080 is occupied, go straight to locating and freeing port 3080.
Sources: apps/cli/README.md, apps/desktop/README.zh.md, Microsoft Learn · netsh.
FAQ
In DeepSeek Harness, three classes by error code: address already in use means another process holds the port; permission denied means insufficient privileges or a reserved port range; address unavailable usually means the bind address does not exist on this host. Each has a different fix — change the port or stop the holder, move to a high port, or correct the bind address.
In DeepSeek Harness, use the system tools to list the process holding the port, then decide whether to stop it or change ports. In most cases changing the dsh web port is faster than investigating the holder; only investigate when you must keep that port, for example because it is already in proxy configuration or team documentation.
In DeepSeek Harness, low ports, generally those below 1024, require elevated privileges to bind. Running as a non-root user in a container or as a normal user on the host will be refused. Move to a high port rather than running with elevated privileges, which increases risk for little benefit.
In DeepSeek Harness, the port may fall inside the system's dynamic or reserved range. Those ports are not occupied by ordinary programs but still reject binding, often returning a permission-style error that looks like a privilege problem. Choose a port clearly outside the reserved range, or consult the official documentation for how to inspect the range on your machine.
DeepSeek Harness entries conflict only if two of them bind the same port. If each uses a different port they coexist. Start by identifying which entry failed and which port it wanted; change only the failing one, since changing all three introduces new problems.
Related Terms
- port in use (EADDRINUSE)
- Address in use means another process already bound the port, so a new bind is refused. It is the most common cause of DeepSeek Harness startup failure; the fix is changing ports or stopping the holder.— https://learn.microsoft.com/windows-server/networking/technologies/netsh/netsh-introduction
- permission-style bind failure (EACCES)
- A permission-style bind failure occurs when privileges are insufficient or the port lies in a system-reserved range, typically with low ports or restricted ranges. The fix is a high port, not repeated retries.— https://learn.microsoft.com/windows-server/networking/technologies/netsh/netsh-introduction
- dynamic and reserved ranges
- Dynamic and reserved ranges are port ranges the operating system sets aside for temporary connections or specific services. Ordinary programs may fail to bind them, which explains the seemingly contradictory case of no holder yet no bind.— https://learn.microsoft.com/windows-server/networking/technologies/netsh/netsh-introduction
- bind address
- A bind address is the local interface a service listens on. Specifying an address the host does not own produces an address-unavailable error, the most easily overlooked of the three port problem classes.— https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.md