What Should You Check When a Docker Container Keeps Restarting?

What does a restart loop mean?

A container repeatedly returning to Restarting usually means its main process has exited and Docker is starting it again because of the configured restart policy.

A restart policy is availability behavior, not a remediation mechanism. It does not resolve why the process exited.

Container starts → Main process exits → Restart policy applies → Container starts again

Start with the exit code

The exit code is the first indicator of how the process ended, but it is not the root cause by itself. It must be correlated with application logs from the same time window.

• Exit code 0: Process may have completed normally
• Exit code 1: General application or startup failure
• Exit code 126/127: Permission, command or path problem
• Exit code 137: Possible SIGKILL or memory pressure
• Exit code 143: Possible controlled SIGTERM shutdown

Application startup logs

Container logs expose stdout and stderr from the image’s main process. Invalid environment variables, migration failures, permissions and connection problems often appear during the first seconds of startup.

Confirm that logs persist across restarts and that you are inspecting the correct container instance.

• Missing or invalid environment variable
• Invalid configuration file
• Unavailable database
• File or directory permissions
• Failed schema migration
• Application cannot bind its listening port

Memory pressure and OOMKilled

If a container exceeds its memory limit, or the host is under severe pressure, the Linux kernel may terminate the process. The restart policy starts it again and the cycle can repeat under the same load.

Increasing the memory limit alone can hide a memory leak or incorrect capacity planning. Host and container consumption should be assessed together.

Incorrect command or entrypoint

An image may be valid while a Compose command or entrypoint override causes its main process to finish immediately.

A daemon that backgrounds itself, a malformed shell expression or a missing executable can all cause an unexpected exit.

Dependencies are not ready

An application may exit if it starts before its database, cache, message broker or external API is ready.

Startup order alone is not sufficient; dependencies need a readiness signal that confirms they can actually accept traffic.

• DNS or service name cannot be resolved
• Database is not accepting connections
• Credentials or secrets are invalid
• TLS verification fails
• Network policy or firewall blocks connectivity

Health checks and restart policies differ

A health check reports whether the application is healthy or unhealthy. In Docker Engine, an unhealthy state alone does not restart the container.

If an orchestrator, watchdog or custom automation converts unhealthy status into a restart, that event chain must be examined separately.

Restart policy behavior

Policies such as always and unless-stopped can restart a container whenever its process exits. on-failure applies when the process exits with an error status.

Resetting the restart count or disabling the policy does not fix the root cause, although a controlled pause can preserve evidence and stop an uncontrolled loop during diagnosis.

A safe diagnostic sequence

Before removing a production container, preserve its state, exit code, restart count, OOM status, health information and recent logs.

• Establish the affected service and user scope
• Record container state and exit code
• Correlate application logs with Docker events
• Review host CPU, memory, disk and inode capacity
• Compare recent environment and secret changes
• Verify dependency connectivity
• Align the first failure with the latest deployment

Interventions to avoid

Deleting containers, clearing volumes or replacing images before collecting evidence can cause irreversible data loss and remove the strongest diagnostic signals.

• Removing the container and volumes together
• Repeating restart commands indefinitely
• Disabling OOM safeguards blindly
• Overwriting environment files with an old copy
• Pulling an unverified latest image
• Recreating the service before preserving logs

When should you seek specialist support?

If the restart loop affects a critical service, risks data consistency or repeatedly follows deployments, the container should not be assessed in isolation.

The image, Compose definition, startup sequence, dependencies, host resources and rollback plan need to be evaluated together.