Fix "exited with code" on Docker
Quick Answer: The "exited with code" Docker error indicates a container process terminated unexpectedly, often due to an application crash or misconfiguration within the container. The most likely cause is an unhandled exception in your application code or an incorrect entrypoint/command. First, inspect the container logs using `docker logs <container_id>` to identify the exact error message. Expect to see application-level errors, missing dependencies, or command execution failures that pinpoint the root cause.
What Causes This Error
- Application process crash: The main process within the container (e.g., Node.js app, Python script) encountered an unhandled exception or critical error, causing it to terminate.
- Incorrect ENTRYPOINT or CMD: The command specified in the Dockerfile or `docker run` command is syntactically incorrect, references a non-existent executable, or has incorrect arguments, preventing the application from starting.
- Missing dependencies or files: The container image lacks critical libraries, configuration files, or application assets required for the application to initialize and run successfully.
- Resource limitations: The container ran out of allocated memory (OOMKilled) or CPU, leading to the operating system terminating the process to prevent system instability.
- Port binding conflicts or network issues: The application inside the container cannot bind to its specified port because it's already in use, or there are network configuration problems preventing it from starting correctly.
- Privilege issues: The container process lacks necessary permissions to access certain directories, files, or system resources it requires to operate.
Step-by-Step Fixes
Fix 1: Inspect Container Logs for Application Errors
Identify the exited container's ID or name using `docker ps -a`.,Retrieve the container's standard output and error streams with `docker logs <container_id_or_name>`.,Analyze the log output for application-specific error messages, stack traces, or dependency warnings that indicate why the process terminated.,If logs are truncated, use `docker logs --tail <number> <container_id_or_name>` or `docker logs --since <timestamp> <container_id_or_name>` for more context.
Fix 2: Verify ENTRYPOINT and CMD Configuration
Review your Dockerfile for the `ENTRYPOINT` and `CMD` instructions. Ensure the executable path is correct and accessible within the container.,Check the `docker run` command for any overrides to `ENTRYPOINT` or `CMD` that might be malformed or pointing to non-existent scripts.,Temporarily modify the `CMD` to `sh` or `bash` (e.g., `docker run -it <image_name> sh`) to enter the container interactively.,Once inside, manually attempt to run your application's entrypoint command to debug execution issues directly (e.g., `./app.sh` or `python main.py`).
Fix 3: Check for Missing Dependencies and Files
Examine your Dockerfile for `COPY` or `ADD` instructions to ensure all necessary application files, configuration, and libraries are being included in the image.,Verify that your `requirements.txt`, `package.json`, or similar dependency files are correctly specified and that the `RUN pip install -r requirements.txt` or `npm install` commands are executing successfully during image build.,Use `docker run -it <image_name> ls -l /path/to/expected/file` to confirm the presence and permissions of critical files within a running container.,If using bind mounts, ensure the host path exists and contains the expected files, and that the container user has appropriate read/write permissions.
Fix 4: Adjust Resource Limits
Review the `docker logs <container_id>` output for `OOMKilled` or similar memory-related messages.,If resource exhaustion is suspected, increase the memory or CPU limits when running the container. For example, `docker run -m 2g --cpus 1.5 <image_name>` for 2GB memory and 1.5 CPU cores.,Monitor container resource usage during startup with `docker stats <container_id>` in a separate terminal to identify spikes or sustained high consumption.,Optimize your application's resource footprint: reduce memory usage, optimize algorithms, or use a smaller base image if possible.
Fix 5: Resolve Port Binding and Network Conflicts
Ensure the port your application inside the container is trying to bind to (e.g., `EXPOSE 8080`) is not already in use on the host machine or by another container.,Check the container's network configuration. If using custom networks, verify that the container is attached to the correct network and can resolve necessary hostnames.,Temporarily remove `-p` (port mapping) from `docker run` to see if the container starts successfully without external port exposure, indicating a host port conflict.,Use `netstat -tulnp | grep <port_number>` on the host to identify processes already listening on the desired port.
Advanced Fixes
Advanced Fix 1: Utilize Docker Debugging Tools and Entrypoint Overrides
Run your container with an interactive shell: `docker run -it --entrypoint /bin/bash <image_name>` (or `/bin/sh`). This allows you to explore the container's environment, check file paths, permissions, and manually execute commands.,Mount your application code as a volume for live debugging: `docker run -v $(pwd)/app:/app <image_name>`. This allows you to modify code on your host and see changes reflected instantly inside the container without rebuilding the image.,Use `strace` or `ltrace` (if available in the base image, or installed temporarily) to trace system calls or library calls made by your application process. This can reveal low-level issues like file access failures or incorrect library linkages. Example: `docker run --cap-add SYS_PTRACE <image_name> strace -f <your_command>`.
Advanced Fix 2: Analyze Container cgroup Events and Kernel Logs
For suspected OOMKilled issues not clearly logged by Docker, check the host system's kernel logs: `dmesg -T | grep -i oom-killer` or `journalctl -xe | grep -i oom-killer`. This provides direct evidence of the kernel terminating processes due to memory pressure.,Examine cgroup events for resource constraint violations. You can find cgroup paths for a container using `docker inspect <container_id> | grep CgroupParent`. Then, check relevant cgroup event files (e.g., `/sys/fs/cgroup/memory/<cgroup_path>/memory.events`) for `oom_kill` or `memory.failcnt`.,If using Docker Compose, consider using `docker-compose up --abort-on-container-exit` during development to stop all services if one exits, simplifying debugging of interdependent services.
FAQs
Q: What does 'exited with code 0' mean?
A: An exit code of 0 typically indicates that the container's main process terminated successfully, as expected. This is common for batch jobs or scripts that run to completion. If your long-running service exits with code 0, it means the application itself finished its task and shut down, which might be unexpected if you intended it to run indefinitely. Check if your `CMD` or `ENTRYPOINT` is designed for a one-off task.
Q: How do I find the specific exit code for my container?
A: You can find the exit code using `docker ps -a` which lists all containers, including exited ones, and displays their status including the exit code. Alternatively, after a container exits, you can use `docker inspect <container_id_or_name>` and look for the `State.ExitCode` field in the JSON output.
Q: My container exits immediately with code 137. What does that signify?
A: Exit code 137 (128 + 9) usually indicates that the container's main process was terminated by a `SIGKILL` signal. This is most commonly caused by the Docker daemon or the host operating system forcibly stopping the container due to an Out Of Memory (OOM) error. Check `docker logs` for `OOMKilled` messages and consider increasing the container's memory limits using the `-m` flag.
Q: Why does my container exit with code 126 or 127?
A: Exit code 126 means 'command invoked cannot execute', often due to incorrect permissions on the executable or the file not being an executable. Exit code 127 means 'command not found', indicating that the `ENTRYPOINT` or `CMD` specified in the Dockerfile or `docker run` command does not exist in the container's PATH or at the specified absolute path. Verify paths and permissions.
Q: Can I prevent a container from exiting immediately for debugging?
A: Yes, you can temporarily override the container's `CMD` or `ENTRYPOINT` to keep it running. For example, `docker run -it <image_name> bash` (or `sh` if bash isn't available) will start an interactive shell. This allows you to inspect the container's filesystem, environment variables, and manually attempt to run your application's commands to diagnose issues.