Docker container keeps restarting: diagnose exit state, configuration and resource failures

The release command finishes, but the application remains unavailable and the same startup message appears every few seconds. Increasing the restart count does not help. The configured main process is still failing for the same reason.

When a Docker container keeps restarting, capture the exit evidence before changing anything. The steps read exit state in a Docker restart loop, check whether Docker exit code 137 really came from an out-of-memory kill, validate the entry point and configuration, and verify one fix.

When a Docker container keeps restarting, capture the exit evidence before changing commands, credentials or memory limits. This guide separates a process exit from an unhealthy check and follows the failure from the selected artifact to the public request path.

Our production Node.js image guide explains the underlying artifact. Keep retained database and upload storage untouched while diagnosing its operating lifecycle.

Step 1: Scope the selected service

Confirm the Compose project, file set and service involved. Do not inspect or restart every container on a shared machine. The following commands illustrate a known acme-prod project and web service:

docker compose --project-name acme-prod --file compose.yaml ps --all web
docker compose --project-name acme-prod --file compose.yaml \
  logs --no-color --tail 100 web

Read the transcript privately because application logs can contain sensitive data. Preserve the first useful error and time, not only the final repeated banner.

Find the actual container ID from the scoped service listing. Names vary with project and container naming configuration; do not assume an example name identifies the intended application.

Step 2: Read exit state and restart behavior

Inspect only the needed state fields rather than dumping configuration and environment values. For a confirmed container name, an illustrative command is:

docker inspect acme-prod-web-1 \
  --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} restarts={{.RestartCount}}'

Compare those fields with the selected restart policy and host timeline. A policy can repeat a failure but does not repair missing files or credentials.

Do not call every unhealthy container a restart loop. Normal standalone restart policies react to process exit; another orchestrator or watcher may have a separate health-based action.

Step 3: Validate the entry point and artifact

Check that the final image contains the intended server path and dependencies. A development command, completed migration command or shell script that backgrounds the server can cause the main container process to finish unexpectedly.

Review working directory, command overrides, executable permissions and platform architecture. An exec-format failure needs a compatible artifact or interpreter contract, not broader file permissions.

A bind mount can hide code or dependencies copied into the image. Compare effective mounts with the image's expected filesystem before rebuilding the application unnecessarily.

Step 4: Diagnose required configuration

Check the names and delivery mechanism for required environment values or secret files without printing their contents. A mounted secret is not automatically read by every framework or image.

Verify the configured private service address from inside the intended network. localhost inside a container identifies that container, not a separate database service or the host by default.

Classify a dependency failure: name resolution, connection refusal, authentication or application schema mismatch. Repeated restarts can amplify connection attempts without making the dependency ready.

Step 5: Investigate memory with corroborating evidence

An exit code alone does not establish the memory cause. Correlate OOMKilled, container limits, host pressure and the application's activity before termination.

Compare normal startup demand with the failing workload. An image that tries to compile during startup can have a very different memory profile from one that starts an already built server.

Do not raise memory for every service after one failure. Fix unbounded allocation or concurrency where possible and verify host headroom before increasing a reviewed limit. Our Node.js memory-leak guide covers application evidence.

Step 6: Reproduce privately without destructive resets

Use the same artifact in an isolated rehearsal with synthetic data and protected test credentials. Keep payment, mail and other external effects disabled or intentionally sandboxed.

If the process exits too quickly for exec, inspect the artifact through a deliberately selected diagnostic command in the rehearsal environment. Do not repeatedly recreate the live database or remove its volume to make the application boot.

When an incompatible database format or permissions problem is involved, preserve the retained state and obtain the correct compatible operating procedure. A successful empty initialization is not recovery of the customer's records.

Step 7: Correct one cause and verify stability

Apply the reviewed artifact, entry-point or configuration correction. Recreate only the intended service through its existing release process. Keep a compatible previous image and configuration available.

Watch restart count and response failures together. A stable process that cannot serve authenticated requests has not completed recovery.

Step 8: Preserve the incident record

Record the first error, exit evidence, diagnosed boundary and targeted correction. Remove temporary diagnostics through the same scoped review, while retaining enough evidence for future incidents.

Do not use global image or volume pruning as the final cleanup step. For a container lifecycle and reliability review, contact Cloudsoft Zone.

Featured image: Cloudsoft Zone technical layout with docker artwork by dotCloud, Inc. (Apache License 2.0). Product mark resized proportionally for identification; no endorsement implied. Layout: CC BY-SA 4.0.