When a Docker service exits, cannot be reached, reports an unhealthy status, or appears to lose its data, the fastest fix is a structured diagnosis rather than repeated restarts. This guide provides a reusable workflow for inspecting containers, logs, ports, environment variables, health checks, volumes, permissions, and image architecture with Docker CLI and Compose.
Overview
Docker problems often look similar from the outside: an API returns a connection error, a database is unavailable, or a container disappears from the running list. The underlying causes are different, however. A process may have completed normally, crashed during startup, listened only on the loopback interface, received the wrong environment variable, failed a health check, or mounted an unexpected directory over its application files.
Start by separating the symptom from the layer that owns it:
- Process layer: Did the container's main command start and remain running?
- Network layer: Is the service listening on the expected interface and port, and is that port published or addressed correctly?
- Configuration layer: Are required environment variables, secrets, files, and service names available?
- Storage layer: Is the expected volume mounted, writable, and attached to the right container?
- Platform layer: Does the image match the host architecture and runtime assumptions?
Use this distinction to avoid changing several variables at once. Capture the current state first, then make one targeted change and test again.
What to track
A small set of Docker observations is enough to make most troubleshooting sessions repeatable. Record the container name or ID, image tag, command, status, exit code, published ports, health status, mounts, and the first relevant error in the logs.
Symptom-to-cause comparison
| Symptom | Likely areas to inspect | Useful checks |
|---|---|---|
| Container exits immediately | Startup command, missing configuration, application crash, completed one-shot process | docker ps -a, docker logs NAME, docker inspect NAME |
| Port is not accessible | Missing port publication, wrong host port, service bound to 127.0.0.1, firewall, wrong protocol | docker port NAME, inspect port bindings, test from the correct network location |
| Container is unhealthy | Health-check command, startup timing, dependency readiness, incorrect internal port or path | docker inspect --format '{{json .State.Health}}' NAME |
| Service cannot reach another container | Wrong service name, network attachment, port confusion, application binding | Inspect networks and use the Compose service name as the hostname |
| Files or database data appear missing | Wrong volume, bind mount hiding image files, new project path, initialization behavior | docker inspect NAME, inspect the Mounts section |
| Permission denied | Host ownership, container user, read-only mount, security or filesystem restrictions | Compare mount permissions with the process user inside the container |
| Image will not run on the host | CPU architecture mismatch, incompatible native dependency, incorrect platform selection | docker image inspect IMAGE, review image platform metadata and build settings |
Use a consistent inspection sequence
- List all containers, including stopped ones:
docker ps -a. - Read application output:
docker logs --tail 200 NAME. Add-fonly when you need to follow new output. - Inspect state, command, environment, networks, and mounts:
docker inspect NAME. - Check the image's configured command and entrypoint:
docker image inspect IMAGE. - Enter a running container when possible:
docker exec -it NAME sh. Some images providebashinstead ofsh. - Watch lifecycle events during a reproduction:
docker events.
For Compose projects, use the project-aware commands, such as docker compose ps, docker compose logs SERVICE, and docker compose config. The last command is particularly useful for reviewing the resolved Compose configuration, including interpolated variables and merged settings.
Cadence and checkpoints
Docker troubleshooting is not only a one-time repair task. Keep a lightweight checkpoint whenever a service is introduced, upgraded, or moved between machines.
At service creation
Document the expected command, internal listening port, published host port, required variables, health-check behavior, and storage locations. Clarify whether the service is intended to run continuously or exit after completing a job. This prevents a normal one-shot exit from being mistaken for a crash.
After image or Compose changes
Compare the old and new image tags, entrypoint, exposed ports, environment names, mount paths, and declared health check. A container may start successfully while a changed application path, user ID, or initialization routine creates a later failure.
Monthly or quarterly
For active development environments, review stale containers, unused volumes, old image tags, and local overrides. Confirm that important data is stored in an intentional named volume or host path rather than an anonymous container layer. Do not remove volumes as a cleanup step until their contents and ownership are understood.
During an incident
Capture the state before restarting. A restart can remove useful context, especially when the failing container is configured for automatic restart. Save logs, inspect output, the resolved Compose configuration, and the relevant image reference before applying a fix.
How to interpret changes
Container exits and exit codes
A stopped container is not necessarily broken. Containers remain alive only while their main process is running. If a shell, script, migration, or command finishes, Docker may correctly report an exited container. If the process crashes, the logs usually identify the first failure. Check the configured command and entrypoint before replacing them with a long-running placeholder; keeping a container alive can hide the actual application problem.
Ports and networking
A port published with a mapping such as -p 8080:80 connects host port 8080 to container port 80. The application still needs to listen on the container's expected port. Within a Compose network, one service should normally contact another by its service name and internal port, not by the host-published port. Also check whether the application listens on all container interfaces rather than only on loopback.
Health checks
A health check is a separate test of readiness or responsiveness; it does not automatically restart a failing application. Inspect the command, recent health-check output, start period, interval, timeout, and retry settings. A check that runs before the service is ready may produce an unhealthy status even though the application eventually starts. Conversely, a passing process-level status does not prove that the API or database is ready for requests.
Volumes, bind mounts, and permissions
A bind mount can hide files that were present in the image at the same path. A named volume can preserve data across container replacement, but it may be attached to a different service or project than expected. Inspect the mount source and destination rather than assuming the volume name is sufficient. For permission errors, compare the host path ownership with the user configured in the image or Compose service. Avoid broad permission changes until you know which process needs access.
Environment and architecture
Check whether variables were supplied at runtime, whether Compose interpolation produced the intended values, and whether a required file path exists inside the container. Treat secrets carefully: inspect configuration without copying sensitive values into tickets or logs. For architecture failures, compare the host platform with the image's available platform and the requirements of native packages. Rebuild or select a compatible image deliberately rather than assuming emulation will behave like a native build.
When to revisit
Revisit this checklist whenever Docker Engine, Docker Desktop, Compose files, base images, language runtimes, or native dependencies change. Also return to it when a service moves from local development to CI, when a new machine uses a different CPU architecture, or when persistent data appears to disappear after recreation.
Before closing an incident, write down the observed symptom, confirmed cause, command or configuration change, and verification step. Then reproduce the service from the documented Compose or run configuration. A reliable fix should explain why the old behavior occurred, not merely make the container stay running.
For a practical final check, run this sequence:
- Confirm the intended image and resolved configuration.
- Start the service and verify its process status.
- Read startup logs for errors and warnings.
- Test the service from the correct network location.
- Confirm health-check output and dependency readiness.
- Verify that expected files or data are present in the intended mount.
- Record the result so the next failure can be compared against a known-good checkpoint.
This habit turns Docker container troubleshooting from trial and error into a repeatable diagnostic workflow.