RunbooksPort conflicts

Port already in use

Applies to: all

Symptom

Starting a service fails with one of:

Error: listen EADDRINUSE: address already in use 127.0.0.1:3001
Error: bind: address already in use (0.0.0.0:5433)
docker: Error response from daemon: driver failed programming external connectivity ... 0.0.0.0:9000 -> container: address already in use

Likely cause

Another process is already bound to the port. For HiveCFM the usual suspects are:

PortNormally bound by
3000pnpm --filter @hivecfm/web dev (native dev default) or an unrelated Ruby/Puma process on shared VMs
3001hivecfm-core Docker container (HIVECFM_PORT=3001)
3002Superset
4100hivecfm-dev-hub (this site, next dev -p 4100)
5433Postgres exposed by docker-compose.dev-ports.yml
6380RedisRedisIn-memory key-value store used for caching, sessions, and rate limiting. Runs on port 6380 locally. exposed by docker-compose.dev-ports.yml
9000 / 9001MinIOMinIOS3-compatible object storage for survey attachments and uploads. Runs locally; swaps for real S3 in prod. S3 API / MinIO console

A leftover Docker container, a previous pnpm dev that did not exit cleanly, or a system service that was already using the port is almost always the culprit.

Fix

Find what is on the port

On Linux or macOS:

sudo lsof -i :3001
# or, without sudo:
ss -ltnp | grep :3001

On Windows (PowerShell or cmd):

netstat -ano | findstr :3001
tasklist /FI "PID eq <pid-from-above>"

Decide whether it is a HiveCFM container

docker ps --format "table {{.Names}}\t{{.Ports}}" | grep 3001

If it is a HiveCFM container, stop it instead of killing the process:

docker compose stop hivecfm-core

Kill the process if it is not a container

⚠️

fuser -k and kill -9 terminate the target process immediately with no chance to flush state. Save your work first.

# Linux / macOS
sudo fuser -k 3001/tcp
# or, targeted by PID:
kill -9 <pid>
# Windows
taskkill /PID <pid> /F

Re-run the failing command

pnpm --filter @hivecfm/web dev      # or docker compose up -d

Verify

sudo lsof -i :3001           # no output = free
curl -s http://localhost:3001   # 200 once the app boots

Prevent

  • Always stop services with their own command (docker compose down, Ctrl+C in pnpm dev) rather than closing the terminal.
  • If you change HIVECFM_PORT in .env, also update WEBAPP_URL and NEXTAUTH_URL so the app and the listener agree.
  • On shared dev VMs, keep the Run it locally port map pinned — port 3000 is commonly taken, which is exactly why HiveCFM uses 3001 in Docker.
OverviewBuild OOM