🩺 Troubleshooting

Troubleshooting: Docker error messages are like a car dashboard: 'port is already allocated' is not the engine exploding — it is one specific warning light pointing at one specif

Docker error messages are like a car dashboard: 'port is already allocated' is not the engine exploding — it is one specific warning light pointing at one specific subsystem, and this tab is the manual that maps each light to its fuse box. Why memorize error patterns instead of just googling each one as it appears? Because in a broken CI pipeline the clock runs differently: recognizing 'Cannot connect to the Docker daemon' as a service-not-running problem in 10 seconds versus 30 minutes of trial-and-error is the difference between a footnote and a blocked release — exactly like a seasoned Java developer telling NullPointerException from ClassNotFoundException across the room, because each points at a completely different layer. Every error below is real and harvested from actual QA pipelines; learn the shape of each one now, while nothing is on fire.

🎬 The Diagnosis Chain of a Docker Error: "The Container That Exits Instantly"

Exited in < 1 second

`docker run my-image` is run — the container STARTS and STOPS in under a second. Exit code 0, meaning it did not even "error"; it just vanished.

Step 1 — DECOMPOSE the message: exit code 0 is not an ERROR, it means "the process ended cleanly". The problem is not a crash — the problem is that the process never STAYED ALIVE.

Step 2 — collect non-destructive evidence: `docker logs my-container`. The output shows nginx's normal startup messages — NO error, just an early-ending process.

Step 3 — diagnose the ROOT cause: when `CMD ["nginx"]` runs, nginx turns itself into a BACKGROUND DAEMON and the process CMD started immediately ends — Docker says "the main process ended" and shuts the container down.

Step 4 — the smallest SAFE fix: `CMD ["nginx", "-g", "daemon off;"]` — runs nginx in the FOREGROUND. Docker no longer loses track of the process it is watching.

Step 5 — PROVE it with the SAME command: `docker run my-image` runs again. `docker ps` now shows the container as "Up" — not forever, but for as long as the main process lives.

Final — the chain: decompose the message → non-destructive evidence (logs) → root cause → smallest safe fix → prove with the same command. The Java bridge: this is like a `main()` method returning on its very first line — the thread never stayed alive, it never threw an exception.

Step by Step: The Docker Error Diagnosis Reflex

Run `docker ps -a`; 0 means a clean exit, 1+ means an error — but the answer to "which error" is not here.

Collect non-destructive evidence

Start with commands that break nothing: `docker logs`, `docker inspect`, `docker diff` — never start with `rm` or `-f`.