ClavueClavue
CLI · TUI · models

Port Already in Use in a Workspace Pane

Find and free a local port used by a dev server without killing unrelated imux tools.

IntermediateTroubleshooting
portsdev-servertroubleshooting

Agent and human panes often start next dev, Vite, or Docker-published ports. A second start fails with EADDRINUSE.

Fix the owner of the port deliberately—do not kill -9 random PIDs.

Prerequisites

  • macOS terminal in imux
  • Permission to inspect local processes

Steps

  1. 01

    Identify the port from the error

    Read the failing command output for the port (3000, 5173, 8080, …). Confirm whether another imux pane already runs that server.

  2. 02

    Find the listening process

    lsof -nP -iTCP:3000 -sTCP:LISTEN

    Note the PID and command. If it is your previous dev server in another pane, stop it cleanly there (Ctrl+C) instead of force-killing.

  3. 03

    Stop or repoint

    Preferred: stop the old server in its pane. Alternative: start the new service on another port and update browser surfaces/bookmarks.

  4. 04

    Only then force-kill

    kill <pid>
    # last resort:
    kill -9 <pid>

    Avoid killing imux itself or system daemons. If the port is held by Docker, stop the container with Docker tooling.

FAQ

imux listening ports list empty?

The sidebar port scanner may lag; lsof is authoritative on the host.