Check container logs using docker logs [container_id] to identify startup errors like missing files or dependency failures. 2. Run the container interactively with docker run --rm -it --entrypoint /bin/sh image_name to inspect environment and manually test commands. 3. Examine exit codes via docker ps -a—code 0 for success, 1 for application error, 127 for command not found—and use docker inspect [container_id] for detailed status. 4. Validate configuration of ports, volumes, networks, and environment variables, testing with minimal settings to isolate issues. Most problems are resolved by analyzing logs, exit codes, and interactive debugging.

When a Docker container fails to start, it can be due to configuration errors, resource limits, application crashes, or misconfigured dependencies. The key is to systematically isolate the cause using built-in Docker tools and logs.

Check Container Logs

Use docker logs [container_id] to view the output from the container. Even if the container exits immediately, Docker retains the logs.

• If the container never started, you may see command not found, missing files, or application startup errors.
• Look for stack traces, permission issues, or failed dependency loads (e.g., database connection errors).
• If the container ID isn’t known, use docker ps -a to list stopped containers and find the relevant one.

Run in Interactive Mode for Debugging

Start the container with an interactive shell instead of the default command to inspect its environment.

• Override the entry point: docker run --rm -it --entrypoint /bin/sh image_name
• Once inside, check if required files exist, services are installed, or environment variables are set correctly.
• Try manually running the application command to see immediate errors.

Inspect Exit Code and Status

The exit code from docker ps -a gives clues about what went wrong.

• Exit code 0 means success (but the process may have exited too soon).
• Code 1 usually indicates a general error—often a crash in the application.
• Code 127 suggests a command not found—likely a typo in CMD or missing binary in the image.
• Use docker inspect [container_id] to get detailed info including restart policy, mounted volumes, and exact failure timestamps.

Validate Configuration and Dependencies

Misconfigurations in ports, volumes, networks, or environment variables can prevent startup.

• Ensure ports aren’t already in use on the host (-p 8080:80 failing if 8080 is busy).
• Verify volume paths exist and have correct permissions.
• Confirm linked services or networks are running if your container depends on them.
• Test with minimal config: remove volumes, ports, and env vars one by one to isolate the issue.

Basically, start with logs and exit codes, then test interactively. Most startup problems reveal themselves quickly once you see the actual error output or can explore the container’s filesystem.

The above is the detailed content of How to troubleshoot 'Docker container not starting' issues?. For more information, please follow other related articles on the PHP Chinese website!