PortClash

Find port already in use before you run anything.

Error: listen EADDRINUSE: address already in use :::3000. You have seen it this week. Usually the cause is sitting in the repo already: the compose file publishes 3000, the admin app's vite.config.ts also says 3000, and the web app runs next dev, which defaults to 3000. Nobody wrote the three down side by side, so you only find out when the second one crashes, or worse, when Vite quietly moves to 3001 and your OAuth callback stops working.

PortClash reads every place a port is declared in your workspace, lines them up, and reports the conflicts in the Problems panel with links between the clashing lines.

• PC001 two different sources bind the same host port (Error)
• PC002 port 5000/7000 (AirPlay on macOS) or a privileged port for a dev server (Information)
• PC003 a compose database or cache is published on 0.0.0.0 instead of 127.0.0.1 (Warning)
• PC004 a PORT fallback in code disagrees with .env / compose (Information)
• PC005 optional: a declared port is already in use on this machine right now (Information)

Where you see the results:

• Problems panel: one diagnostic per finding, with related links to the other lines.
• Activity bar: a PortClash view (Ports) lists every declared port, findings first. Each row is labelled with the code and the exact port (PC001 3000/tcp, PC003 5432/tcp, 6379/tcp) and described with the rule and its owners (port clash: next dev (apps/web/package.json), service api (compose.yaml)). Expand a row to see the exact lines that claim the port and click one to jump to it. The badge shows the number of clashes; the title bar has Find Free Port Near..., Show Port Map and Refresh, and every host port row has an inline Find Free Port Near... button.
• Status bar: a plug icon with Ports: 9 · 1 clash; click it for the full port map.

Sources

Only documented keys and documented framework defaults are used.

Two sources that are really the same service are not reported against each other: scripts in the same package (for example next dev and next start), a config file and the scripts next to it (a vite.config.ts and its vite script), compose files for the same service, and any sources that resolve their port through the same .env entry.

Rules

PC004 recognises process.env.X || N, process.env.X ?? N, Number(process.env.X) || N, process.env["X"] || "N", os.getenv("X", "N") and os.environ.get("X", N) for PORT and *_PORT variables, and compares them with the nearest .env and with the environment: of the compose service whose build context contains the file.

How this differs from existing tools

• Port managers and killers (Port Authority, Port Occupancy, Port, "kill port" extensions and CLIs) look at what is listening right now and help you stop it. They answer "who holds 3000?". PortClash answers the question before that: "which two things in this repo both want 3000?". It works without anything running, in a fresh clone or a PR checkout, and never kills processes.
• Compose linters (for example DCLint's no-duplicate-exported-ports rule) check duplicates inside compose files. PortClash also sees the dev servers, framework defaults, .env interpolation, devcontainer, launch configs and port-forwards that clash with compose.
• VS Code's own port forwarding quietly picks another local port when one is busy. That hides the clash instead of reporting it.

Commands

Settings

Privacy

• No telemetry, no requests to any remote host, no child processes. Files are only read, never written. The only local connection is the optional live check on macOS and Windows (below).
• The static rules (PC001 to PC004) only read files in the workspace, so PortClash runs in untrusted workspaces too.
• The live check (PC005) is off by default. When you turn it on:
  • Linux: it reads /proc/net/tcp and /proc/net/tcp6 and looks at sockets in the LISTEN state. No socket is opened.
  • macOS and Windows: for each declared port of 1024 or above, it opens and immediately closes a local connection to 127.0.0.1:<port> only (300 ms timeout); no data is sent. If the connection is accepted, the port is in use and nothing is bound. This catches servers that listen on all interfaces (0.0.0.0), which these systems would otherwise let a loopback bind sit next to. If the connection is refused, it creates a server with Node's net module, calls listen({ port, host: "127.0.0.1", exclusive: true }), and closes it right away; EADDRINUSE means the port is taken. It only binds to loopback, which does not normally trigger a firewall prompt. Every socket is closed on every path (free, in use, error or timeout), a port below 1024 is never touched, and one check stops after 5 seconds. Results are reused for 30 seconds unless you press Refresh.
  • While a workspace is untrusted, portClash.checkListening is only honoured from your user settings, never from the workspace's .vscode/settings.json.
• Find Free Port Near... runs only when you invoke it and uses the same method (on Linux, /proc/net/tcp first, so a port that is already listening is never bound, then the loopback listen probe to confirm; on macOS and Windows, the local connection first, then the listen probe).
• Files reached through a symlink that leads outside the workspace folders are never read, and the view only opens files of the current scan inside the workspace.
• With Remote - SSH, WSL or Dev Containers the extension runs on the remote side, so the live check describes that machine.

Limitations

• Static and best-effort: ports computed at runtime (port: getPort(), values from a secrets manager, PORT injected by a PaaS) are not seen. JS config files are read with patterns, not executed.
• Compose files are treated per project folder; -f combinations, profiles and extends are not evaluated, and all services are assumed to run together. Nested interpolation beyond one level of default is not resolved.
• Two services that are never started at the same time (for example a Makefile target that runs Postgres in docker run as an alternative to compose) are still reported; use portClash.ignorePorts or rename the port.
• Only documented framework defaults are assumed (listed above). webpack serve has no assumed default; Remix and SvelteKit run through Vite and are covered by the Vite rule.
• Next.js reads PORT only from the real environment, not from .env, so a .env PORT does not change the next dev port.
• The live check on macOS/Windows looks at 127.0.0.1 only: a process that listens on a single other interface (not loopback and not all interfaces) may not be detected. Ports below 1024 are not probed. Ranges are checked for their first 64 ports.
• Kubernetes scopes are separate from the host: a nodePort never clashes with a local dev server.

License

MIT - included with the extension.