How do you debug a container that exits immediately on start?
Learn why Docker containers exit on start and how to debug with exit codes, docker logs, entrypoint overrides, and keeping PID 1 in the foreground.
Expected Interview Answer
A container exits immediately when its main process (PID 1) finishes or crashes, because a container lives only as long as that process runs. You debug it by inspecting the exit code and logs, then reproducing the process interactively to see why it stops.
Start with docker ps -a to see the status and exit code, and docker logs <container> for the process output and errors. Common causes are a command that runs once and exits, a missing binary or bad ENTRYPOINT/CMD, a crash from a missing config or environment variable, or a foreground process that daemonizes and lets PID 1 exit. Reproduce by overriding the entrypoint with an interactive shell (docker run -it --entrypoint sh image) and running the command by hand, or use docker inspect to confirm what command is actually being executed.
- Exit code quickly narrows the cause (0 vs non-zero)
- docker logs surfaces stack traces and missing-file errors
- Overriding the entrypoint lets you run the command manually
- docker inspect confirms the effective CMD/ENTRYPOINT
- Distinguishes a clean finish from a real crash
AI Mentor Explanation
A container that exits instantly is like an innings that ends on the first ball. To debug, you check the scorecard for how the wicket fell (the exit code), review the umpire's notes (docker logs), then send the batter back to the nets to face the same delivery slowly (an interactive shell) until you see exactly why they got out.
Step-by-Step Explanation
Step 1
Check status and exit code
Run docker ps -a and read the STATUS column; an exit code of 0 means clean finish, non-zero means a crash.
Step 2
Read the logs
Run docker logs <container> to see stdout/stderr — stack traces, missing files, or config errors usually appear here.
Step 3
Confirm the effective command
Use docker inspect to check the actual ENTRYPOINT and CMD, since an unexpected command is a frequent cause.
Step 4
Reproduce interactively
Override the entrypoint: docker run -it --entrypoint sh <image>, then run the intended command by hand to watch it fail.
Step 5
Fix the root cause
Address the finding — keep the process in the foreground, supply the missing env var/file, or correct the CMD — and rebuild.
What Interviewer Expects
- Understanding that a container lives only as long as PID 1
- Using docker ps -a and the exit code to triage
- Reading docker logs for the failure reason
- Overriding the entrypoint to debug interactively
- Knowing the difference between a foreground and a daemonized process
Common Mistakes
- Ignoring the exit code and guessing blindly
- Not checking docker logs before restarting repeatedly
- Running the app as a background/daemon process so PID 1 exits
- Assuming the container 'hung' when it actually finished with exit 0
- Adding sleep infinity to hide the crash instead of fixing it
Best Answer (HR Friendly)
“A container only stays alive while its main program runs, so if that program finishes or crashes, the container stops instantly. You debug it by checking the exit code and logs, then opening a shell inside the image to run the command manually and see what breaks.”
Code Example
# See the container, its status and exit code
docker ps -a
# Read the process output and errors
docker logs my-container
# Confirm the command that actually ran
docker inspect -f 'Entrypoint={{.Config.Entrypoint}} Cmd={{.Config.Cmd}}' my-image# Override the entrypoint and get a shell to run the command by hand
docker run -it --entrypoint sh my-image
# Inside the container, run the real command and watch it fail
/app/start.sh# BAD: nginx daemonizes, PID 1 exits, container stops
CMD ["nginx"]
# GOOD: run in the foreground so PID 1 stays alive
CMD ["nginx", "-g", "daemon off;"]Follow-up Questions
- Why does a container stop when its PID 1 process exits?
- What does an exit code of 0 versus 137 tell you?
- How do you keep a debugging container running long enough to exec into it?
- Why must the main process run in the foreground?
- How is docker logs different from exec-ing into a running container?
MCQ Practice
1. Why does a Docker container exit immediately after starting?
A container runs only as long as its PID 1 process; when that process exits or crashes, the container stops.
2. Which command is the best FIRST step to see why a container exited?
docker logs shows the process stdout/stderr, which usually contains the crash reason or missing-file error.
3. How can you run the image's command manually to debug it?
Overriding the entrypoint with an interactive shell lets you run the intended command by hand and watch it fail.
Flash Cards
Why do containers exit immediately? — The main PID 1 process finished or crashed; a container lives only as long as it.
First triage commands? — docker ps -a (status + exit code) then docker logs <container>.
Exit code 0 means? — The process finished cleanly — often a one-off command, not a crash.
How to debug interactively? — docker run -it --entrypoint sh <image> and run the command by hand.
Foreground fix example? — CMD ["nginx", "-g", "daemon off;"] keeps PID 1 alive.