# Docker Cannot Start Container: Complete Troubleshooting Guide
You ran docker run or docker start, but the container won't start. The error message might be cryptic, or worse—the container exits silently. Let me walk you through diagnosing and fixing this common Docker headache.
Common Error Messages
When a container fails to start, you might see one of these:
Error response from daemon: driver failed programming external connectivity on endpoint myapp:
Bind for 0.0.0.0:8080 failed: port is already allocatedError response from daemon: Cannot start container abc123: [8] System error: no space left on deviceError response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "exec: \"myapp\": executable file not found in $PATH"Step 1: Check Container Status and Logs
First, see what's actually happening with your container:
```bash # List all containers, including stopped ones docker ps -a
# Check the container's exit code docker inspect --format='{{.State.ExitCode}}' <container_id>
# View container logs docker logs <container_id>
# For more detail, inspect the container state docker inspect <container_id> | grep -A 20 "State" ```
The exit code tells you a lot: - Exit code 0: The container started but completed its task - Exit code 1: Application error inside the container - Exit code 137: Container was killed (OOM or manually) - Exit code 139: Segmentation fault inside the container
Step 2: Diagnose Port Conflicts
Port conflicts are the most common reason containers won't start. Here's how to track them down:
```bash # Check what's using a specific port netstat -tulpn | grep :8080
# On macOS or Linux with ss ss -tulpn | grep :8080
# Or use lsof lsof -i :8080
# Check for other Docker containers using the port docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Ports}}" | grep 8080 ```
Solution: Either stop the conflicting container or use a different port:
```bash # Stop the conflicting container docker stop <conflicting_container>
# Or map to a different host port docker run -p 8081:80 myimage ```
Step 3: Check Resource Constraints
A container might fail to start if the host lacks resources:
```bash # Check Docker disk usage docker system df
# Check available memory free -h
# Check Docker daemon logs for resource errors journalctl -u docker.service | tail -50 ```
Fix disk space issues:
```bash # Clean up unused Docker resources docker system prune -a
# Remove specific unused volumes docker volume prune ```
Fix memory issues:
# Adjust container memory limits
docker run --memory="512m" --memory-swap="1g" myimageStep 4: Verify Image Integrity
Sometimes the image itself is corrupted or missing required files:
```bash # Inspect the image docker image inspect myimage:latest
# Try pulling a fresh copy docker pull myimage:latest
# Check if the image exists locally docker images | grep myimage ```
If the image layer is corrupted, remove and re-pull:
docker rmi myimage:latest
docker pull myimage:latestStep 5: Check Entrypoint and Command
A common issue is an invalid entrypoint or command in the Dockerfile:
```bash # Check the image's entrypoint docker image inspect --format='{{.Config.Entrypoint}}' myimage:latest
# Check the default command docker image inspect --format='{{.Config.Cmd}}' myimage:latest ```
Test with an interactive shell:
```bash # Override the entrypoint to debug docker run --entrypoint /bin/sh -it myimage:latest
# Once inside, check if your binary exists ls -la /usr/local/bin/ which myapp ```
Step 6: Network Issues
Network problems can prevent container startup:
```bash # List Docker networks docker network ls
# Check network details docker network inspect bridge
# Try with host networking docker run --network host myimage:latest ```
Create a new network if the default is corrupted:
docker network create mynetwork
docker run --network mynetwork myimage:latestStep 7: Volume Mount Problems
Mounting volumes to non-existent paths causes startup failures:
```bash # Check if the host path exists ls -la /path/to/host/volume
# Verify volume mount syntax docker run -v /host/path:/container/path myimage # Or with explicit mount type docker run --mount type=bind,source=/host/path,target=/container/path myimage ```
Quick Reference: Common Fixes
| Error | Solution |
|---|---|
| Port already allocated | Use different port or stop conflicting container |
| No space left on device | Run docker system prune -a |
| Executable not found | Check Dockerfile ENTRYPOINT/CMD |
| Permission denied | Add user to docker group or use sudo |
| Network not found | Create network or use default |
Verification Steps
After fixing, verify the container starts correctly:
```bash # Start the container docker run -d --name test-container myimage:latest
# Check it's running docker ps | grep test-container
# Follow the logs docker logs -f test-container
# Check container health docker inspect --format='{{.State.Health.Status}}' test-container ```
Prevention Tips
- 1.Use specific image tags instead of
latestto avoid unexpected changes - 2.Set resource limits to prevent OOM kills
- 3.Implement health checks in your Dockerfile
- 4.Use docker-compose for complex setups to ensure proper ordering
- 5.Monitor disk space proactively with
docker system df
Container startup issues usually have straightforward fixes once you identify the root cause. Start with logs and exit codes, then work through port conflicts, resources, and configuration issues systematically.