What's Actually Happening
Your Docker container starts, runs for a fraction of a second, and then exits unexpectedly. This is one of the most common Docker issues, and the container might show exit codes like 0, 1, or 137. The container isn't crashing due to a bug—it's simply finishing its work and shutting down, or encountering an error that forces termination.
The Error You'll See
```bash $ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES a1b2c3d4e5f6 my-app "./start.sh" 5 seconds ago Exited (0) 4 seconds ago my-container
$ docker logs my-container # Often empty or very brief output
$ docker ps -a --filter "status=exited" CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES a1b2c3d4e5f6 my-app "./start.sh" 5 seconds ago Exited (1) 4 seconds ago my-container ```
Why This Happens
- 1.Missing foreground process: Containers exit when their primary process (PID 1) completes. If your app runs a quick task and finishes, the container stops.
- 2.Entrypoint script errors: A script with errors or missing execute permissions will fail immediately.
- 3.Missing dependencies: Your application might fail because required files, environment variables, or services aren't available.
- 4.Permission issues: The container user may lack permissions to execute the command or access required files.
- 5.Resource constraints: Exit code 137 indicates the container was killed due to memory limits (OOM Killed).
Step 1: Check the Exit Code and Logs
First, identify why the container exited:
```bash # Check container status and exit code docker ps -a
# View container logs docker logs <container-id>
# If logs are empty, check with timestamps docker logs -t <container-id>
# For stopped containers, inspect the exit code docker inspect <container-id> --format='{{.State.ExitCode}}' ```
Exit codes indicate the problem: - 0: Process completed successfully (usually missing foreground process) - 1: Application error - 126: Command not executable - 127: Command not found - 137: SIGKILL (OOM killed or manually stopped) - 139: Segmentation fault
Step 2: Fix Missing Foreground Process
If exit code is 0, your process finished and exited. Add a foreground process:
For a shell script: ```dockerfile # Bad - script runs and exits CMD ["./start.sh"]
# Good - script keeps running CMD ["./start.sh", "&&", "tail", "-f", "/dev/null"]
# Better - use exec form with proper process ENTRYPOINT ["./start.sh"] CMD ["--foreground"] ```
For a web application:
``dockerfile
# Ensure your app runs in foreground mode
CMD ["node", "server.js"]
# Or for Python
CMD ["python", "-u", "app.py"]
# Or for Nginx
CMD ["nginx", "-g", "daemon off;"]
Step 3: Fix Entrypoint Script Issues
If your entrypoint script has errors:
```bash # Check script permissions docker exec <container-id> ls -la /path/to/script.sh
# Test the script manually docker run -it --entrypoint /bin/bash <image-name> # Then inside container: ./start.sh ```
Fix the script in your Dockerfile:
``dockerfile
# Ensure script is executable
COPY start.sh /start.sh
RUN chmod +x /start.sh
ENTRYPOINT ["/start.sh"]
Step 4: Debug with Interactive Shell
Run the container interactively to diagnose issues:
```bash # Start with interactive shell docker run -it --entrypoint /bin/bash <image-name>
# Or if container keeps exiting docker run -it --rm <image-name> /bin/bash
# Inside container, test your command manually ./start.sh ```
Step 5: Fix OOM Killed Containers (Exit Code 137)
If your container is being killed due to memory limits:
```bash # Check if container was OOM killed docker inspect <container-id> --format='{{.State.OOMKilled}}'
# Increase memory limit docker run --memory="2g" <image-name>
# In docker-compose.yml services: myapp: image: my-app deploy: resources: limits: memory: 2G ```
Step 6: Fix Missing Dependencies
Check for missing files or environment variables:
```bash # Run container with verbose logging docker run -e LOG_LEVEL=debug <image-name>
# Check working directory docker run -it --entrypoint /bin/bash <image-name> ls -la /app
# Verify environment variables docker inspect <container-id> --format='{{json .Config.Env}}' ```
Verify the Fix
After applying fixes, verify your container stays running:
```bash # Run the container docker run -d --name test-container <image-name>
# Check it's running docker ps
# Should show "Up" status CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES a1b2c3d4e5f6 my-app "./start.sh" 5 seconds ago Up 4 seconds test-container
# Check logs for normal operation docker logs -f test-container
# Verify the process is running docker exec test-container ps aux ```
Your container should now stay running and show "Up" status in docker ps.