Docker’s -d (or --detach) flag is used to run containers in the background, allowing you to continue using your terminal. But many developers encounter a confusing issue:
“I ran
docker run -d, but my container stopped immediately. Why?”
In this blog, we’ll explore why Docker containers sometimes exit right after starting and how to diagnose and fix the issue.
🧠 The Core Principle: Docker Containers Run a Main Process
A Docker container is designed to run a single process, and it stops when that process exits.
When you use:
docker run -d my-image
Docker starts a container from my-image, runs its default command, and detaches your terminal. If that command finishes right away, the container exits immediately.
✅ Step 1: Check What Command the Container Is Running
You can inspect the default command defined in the image by running:
docker inspect my-image
Look for the Cmd and Entrypoint fields in the output.
Alternatively, override the default command at runtime:
docker run -d my-image some-command
✅ Step 2: View Container Logs
To see what happened before the container exited:
docker logs <container-id>
This often reveals errors like:
- “command not found”
- “missing environment variables”
- application-specific runtime errors
🔍 Common Reasons Containers Exit Immediately
1. No Command or Invalid Command
If your Dockerfile doesn’t have a valid CMD or ENTRYPOINT, or you override it incorrectly, the container starts and exits instantly.
FROM alpine
This image does nothing unless you specify a command. You can run it properly with:
docker run -d alpine sleep 1000
2. Short-lived Script or Process
If your app finishes quickly (e.g., a script that runs and exits), the container stops because its job is done.
Fix: Add a long-running process or keep the container alive with something like:
CMD ["tail", "-f", "/dev/null"]
Use this only for debugging or development—not for production.
3. Application Crash or Error
Your container might be crashing due to:
- Missing configuration or environment variables
- File system errors
- Port conflicts
Use docker logs or docker inspect to debug further.
🔁 Restart Policy ≠ Keep Alive
Using --restart=always doesn’t prevent a container from stopping—it just restarts it if it exits. If the container crashes immediately and repeatedly, this can lead to restart loops.
docker run -d --restart=always my-image
Use with caution and ensure the root cause is resolved.
🧪 Debugging Tips
- Run the container interactively to troubleshoot:
docker run -it my-image sh - Override the command:
docker run -d my-image tail -f /dev/null - Use
docker ps -ato see containers that exited:docker ps -a
✅ Best Practices
| Tip | Why |
|---|---|
Always define a CMD or ENTRYPOINT in your Dockerfile | So the container knows what to run |
Use docker logs to see why a container exited | It’s your first line of debugging |
| Run in interactive mode for debugging | Easier to inspect the environment |
| Don’t expect containers to “stay alive” without a running process | It’s by design |
Conclusion
If your Docker container stops right after using docker run -d, it’s likely because the container’s main process exited—either by completing its job or due to an error. Docker doesn’t keep containers running unless there’s an active process.
Understanding this behavior helps you build better, more reliable containers. Use logs, inspect commands, and test interactively to get to the root of the issue quickly.