Port already in use during deployment

What this failure means

A container or service failed to start because the port it needs to bind to is already occupied by another process or a previous deployment that has not been fully removed.

Symptoms

Faultline looks for one or more of these log fragments:

port is already allocated
failed to bind to port
port conflict
cannot start service

Diagnosis

A container or service failed to start because the port it needs to bind to is already occupied by another process or a previous deployment that has not been fully removed.

In deploy contexts this usually means a host-port mapping is colliding during rollout, or a prior container still owns the port on the target node.

Fix steps

1. Find the process occupying the port: lsof -i :<port> or ss -tlnp | grep <port>.
2. In Kubernetes with host ports: ensure the old pod is fully terminated before the new one starts, or adjust the rollout strategy so the hand-off is serial.
3. Check for stopped containers: docker ps -a | grep <image> and remove obsolete containers with docker rm.
4. If using NodePort or HostPort in Kubernetes, verify no two pods on the same node request the same port.

Validation

• Re-run the failing workflow step.
• Confirm the original failure signature for Port already in use during deployment is gone.

Why it matters

Ports become stuck when a rolling update leaves an old container alive after the port hand-off, when a host-port mapping conflicts between pods on the same node, or when a local dev service was not shut down before deploying.

Prevention

• Avoid HostPort mappings where possible; use ClusterIP + Ingress instead to let Kubernetes manage port allocation.
• Add a rolling update strategy with maxSurge=0 if host ports must be used, so the old pod is terminated first.
• In local dev, use process supervisors (e.g., docker-compose restart: unless-stopped) so ports are always released on stop.

Try it locally

ss -tlnp | grep <port>
docker ps -a
kubectl get pods -o wide
kubectl rollout status deploy/<name>

How Faultline detects it

Use faultline explain port-conflict to see the full playbook.

faultline analyze build.log
faultline explain port-conflict

Generated from playbooks/bundled/log/deploy/port-conflict.yaml. Do not edit directly.