Docker Container Troubleshooting: Diagnose Exits, Ports, Health Checks, and Volumes
dockercontainersdevopsdebuggingdocker-compose

Docker Container Troubleshooting: Diagnose Exits, Ports, Health Checks, and Volumes

PPrograma Space Editorial Team
2026-11-20
6 min read

Diagnose Docker containers that exit, cannot be reached, fail health checks, lose data, or encounter volume and architecture problems.

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

SymptomLikely areas to inspectUseful checks
Container exits immediatelyStartup command, missing configuration, application crash, completed one-shot processdocker ps -a, docker logs NAME, docker inspect NAME
Port is not accessibleMissing port publication, wrong host port, service bound to 127.0.0.1, firewall, wrong protocoldocker port NAME, inspect port bindings, test from the correct network location
Container is unhealthyHealth-check command, startup timing, dependency readiness, incorrect internal port or pathdocker inspect --format '{{json .State.Health}}' NAME
Service cannot reach another containerWrong service name, network attachment, port confusion, application bindingInspect networks and use the Compose service name as the hostname
Files or database data appear missingWrong volume, bind mount hiding image files, new project path, initialization behaviordocker inspect NAME, inspect the Mounts section
Permission deniedHost ownership, container user, read-only mount, security or filesystem restrictionsCompare mount permissions with the process user inside the container
Image will not run on the hostCPU architecture mismatch, incompatible native dependency, incorrect platform selectiondocker image inspect IMAGE, review image platform metadata and build settings

Use a consistent inspection sequence

  1. List all containers, including stopped ones: docker ps -a.
  2. Read application output: docker logs --tail 200 NAME. Add -f only when you need to follow new output.
  3. Inspect state, command, environment, networks, and mounts: docker inspect NAME.
  4. Check the image's configured command and entrypoint: docker image inspect IMAGE.
  5. Enter a running container when possible: docker exec -it NAME sh. Some images provide bash instead of sh.
  6. 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:

  1. Confirm the intended image and resolved configuration.
  2. Start the service and verify its process status.
  3. Read startup logs for errors and warnings.
  4. Test the service from the correct network location.
  5. Confirm health-check output and dependency readiness.
  6. Verify that expected files or data are present in the intended mount.
  7. 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.

Related Topics

#docker#containers#devops#debugging#docker-compose
P

Programa Space Editorial Team

Developer Resources Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.