You start a Docker container, expect your application to run, and then discover that it has already stopped. Sometimes the container exits within seconds. Other times, it repeatedly restarts without making the application available.

The first step is not to rebuild the image or change the restart policy. It is to find out why the container stopped. Docker provides commands to inspect its logs, exit status, and configuration, which can help you narrow down the cause.

Here is how to troubleshoot a Docker container that exits immediately after startup.

1. List stopped containers

The regular docker ps command shows running containers by default, so a container that has already exited may not appear. Use this command instead:

docker ps -a

Look for your container in the output and check its status. You might see entries such as Exited (0), Exited (1), or Restarting.

The number in parentheses is the exit code reported for that container process. An exit code of 0 generally means the process finished successfully, while a non-zero code usually indicates a failure. However, the code alone does not explain the root cause.

2. Read the container logs

Once you know the container name or ID, retrieve its logs:

docker logs my-container

Replace my-container with the actual name or ID from your output.

To see only the last 100 lines, run:

docker logs --tail 100 my-container

You can also include timestamps when investigating startup failures:

docker logs --timestamps my-container

Look for errors involving missing configuration, failed database connections, unavailable files, invalid commands, permissions, or missing dependencies. The last few log lines before the process exits are often a useful starting point.

If your application is running through Docker Compose, use:

docker compose logs SERVICE_NAME

Replace SERVICE_NAME with the service name defined in your Compose file. To follow logs while a service starts, run:

docker compose logs --follow SERVICE_NAME

Press Ctrl+C to stop following the output. This does not stop the container.

3. Check the exit code and container state

If the logs do not explain the failure, inspect the container’s state:

docker inspect --format='Exit code: {{.State.ExitCode}} | OOM killed: {{.State.OOMKilled}} | Error: {{.State.Error}}' my-container

This command displays the exit code, whether Docker recorded an out-of-memory kill, and any error recorded in the container state.

Use the result to guide the next step:

• Exit code 0: The main process may have completed normally. Check whether the image is intended to run a long-lived server or a one-time task.
• Non-zero exit code: Investigate the application’s logs, startup command, configuration, and dependencies.
• OOM killed is true: Investigate memory usage and the memory limits of your container or environment.
• Restarting: Check whether the process keeps failing and a restart policy is starting it again.

These clues are not definitive diagnoses. For example, exit code 137 often indicates that a process received a SIGKILL signal, but it does not prove that the cause was an out-of-memory event.

4. Check your Dockerfile CMD and ENTRYPOINT

One common reason for a container to exit immediately is that its main command finishes. A Docker container generally runs for as long as its primary process is running. When that process exits, the container stops.

For example, a Node.js application image might contain:

CMD ["node", "server.js"]

Make sure the referenced file exists in the image and that the application starts correctly. If the script runs a task and then exits, the container will stop when that task finishes.

If you intended to run a web server, verify that the command launches the server rather than a build script, a test command, or a short-lived process. Also review any ENTRYPOINT and Compose command settings that might override the expected startup command.

Do not add a command such as tail -f /dev/null just to keep the container alive. That may hide the underlying issue without running your application.

5. Verify environment variables and configuration

Applications commonly exit when required configuration is missing or invalid. This can happen after moving an application from a local development environment to Docker.

Review the environment variables and configuration files expected by your application. For a Compose-based project, check the service’s environment and env_file settings, as well as any referenced environment files.

For example, an application may expect a database URL but receive an empty value, or it may point to a database hostname that cannot be resolved from inside the container.

Remember that localhost inside a container usually refers to that same container, not another service or your host machine. When services communicate over a Docker Compose network, use the appropriate service name as the hostname.

Be careful when sharing logs or configuration output. Environment variables and startup messages can contain passwords, API keys, tokens, and database credentials.

6. Check files, volumes, and permissions

If the logs mention a missing file, permission denial, or a failed configuration load, inspect the image and volume configuration.

Common problems include:

• A file was excluded from the Docker build context or from the image by a .dockerignore rule.
• A volume mount replaced a directory in the image with a host directory that does not contain the expected files.
• The application runs as a user who cannot read a configuration file or write to a required directory.
• A startup script exists but cannot be executed because of its permissions or line endings.

Check the relevant Dockerfile, Compose volume mappings, and file permissions before changing ownership or permissions broadly. Avoid using privileged containers or granting unrestricted access as a quick fix.

7. Rebuild only if the image needs updating

If you changed the Dockerfile, application code, dependencies, or build configuration, rebuild the image and recreate the affected container.

For a Docker Compose project, a typical command is:

docker compose up --build SERVICE_NAME

Use the correct service name and your normal deployment workflow. This command can help when the container is using an outdated image, but it will not automatically fix an incorrect startup command, missing environment variable, or unavailable dependency.

If the image is correct, fix the actual configuration or application problem instead of repeatedly rebuilding it.

8. Why are the logs empty?

If docker logs produces little or no useful output, the application might be writing messages to a file inside the container rather than to standard output or standard error. Docker’s standard log command normally retrieves output from those streams.

Check the application’s logging configuration and the image documentation. The configured Docker logging driver can also affect what is available through docker logs.

If the application never starts far enough to produce its own logs, inspect the container state and startup configuration. If the Docker daemon itself appears to be failing, investigate the daemon logs for your operating system.

Should you use a restart policy?

Docker restart policies can help keep a correctly configured service running after certain failures. However, a restart policy does not fix the cause of a startup error. If the same command fails every time, the container may simply enter a restart loop.

First understand why the process exits. Once the application starts reliably, choose a restart policy that fits the service and your deployment requirements.

Final checklist

• Use docker ps -a to find stopped containers.
• Use docker logs or docker compose logs to examine startup output.
• Inspect the exit code and container state.
• Verify the command, environment variables, files, volumes, and permissions.
• Rebuild the image only when an image or build change is needed.
• Use restart policies only after addressing the underlying failure.

A Docker container that exits immediately is not necessarily broken. It may have completed its task successfully, or it may have failed during initialization. Checking the logs and exit state first helps you distinguish between those cases and choose the right fix.

For further details, read the official Docker documentation on container logs, listing containers, docker inspect, and restart policies.