Port Conflict Playbook
Who this is for
Users whose app fails to start because a port is already in use, or whose container app cannot be reached because the port mapping is wrong.
Understanding Port Conflicts
When you map a container port to a host port (e.g., 80:3000 meaning host port 80 → container port 3000), Docker tries to bind port 80 on the server. If another process is already using port 80, the container will fail to start.
Common port conflicts:
- Port 80 / 443 — Nginx is already using these for sites on the same server
- Port 3000, 8080 — another app is using the same development port
- Port 5432 / 3306 — database already running on the host
Step 1 — Read the Error in App Logs
- Open App detail → Logs.
- Look for:
EADDRINUSE,bind: address already in use,port is already allocated
The error includes the port number that is conflicting.
Step 2 — Find What Is Using the Port
SSH to the server via CloudAIPilot Terminal and run:
sudo ss -tlnp | grep :<PORT>
# or
sudo lsof -i :<PORT>This shows the process name and PID using the conflicting port.
Step 3 — Resolve the Conflict
Option A — Change the App's Host Port
Change the host port your app is mapped to:
- Open App detail → Settings.
- Update the Port mapping to use a different host port.
- Redeploy the app.
Example: If port 8080 is taken, change to 8081.
See KB-04-14: Port Mapping and Conflict Resolution.
Option B — Stop the Conflicting Process
If the conflicting process is not needed:
- Identify it from
ss -tlnpoutput. - Stop it:
sudo systemctl stoporsudo kill. - Restart the app in CloudAIPilot.
Option C — Move Nginx Off Port 80/443
If you want your app to handle port 80 directly (not behind Nginx):
- Stop Nginx:
sudo systemctl stop nginx - Note: this will take all sites on this server offline.
- Preferred approach: keep Nginx running and add a proxy pass from Nginx to your app's internal port instead of mapping to port 80.
Step 4 — Prevent Future Conflicts
Best practices for port assignment:
- Never map apps to port 80 or 443 — let Nginx handle those and proxy to the app.
- Assign unique host ports for each app on the server (e.g., 3000, 3001, 3002…).
- Document port assignments in your team's infrastructure notes.
Common Port Conflicts
| Port | Common owner | Resolution |
|---|---|---|
| 80 | Nginx (sites) | Use Nginx reverse proxy instead of direct bind |
| 443 | Nginx/SSL | Use Nginx reverse proxy instead |
| 3306 | MySQL/MariaDB | Use a different host port for your DB container |
| 5432 | PostgreSQL | Use a different host port for your DB container |
| 6379 | Redis | Use a different host port |