Updated
Docker container exits immediately? Check why it exited from the exit code
Short answer: A Docker exit code is the status the container's main process returned. 0 means it finished normally; 1 and 2 are application errors; 125 means Docker itself failed to run the container; 126 and 127 mean the command could not run or was not found; 137 and 139 mean the process was killed by a signal. Exit code 139 is signal 11, SIGSEGV (a segmentation fault): 128 + 11 = 139. Check State.ExitCode from docker inspect first.
CI says the deploy succeeded, but a few seconds later docker ps -a shows Exited (1) or Exited (127). Users can't reach the app. This guide is for developers and founders who just shipped to a VPS and want a first read of the Docker exit code: confirm the container's state, look up what the code usually means and what it does not prove, then read the exited container's logs to find the first error. If the container keeps flipping to Restarting, that is a restart loop: get the exit code here, then continue with Docker container keeps restarting.
Every command here is read-only. Run them only on a server you are authorized to access, and replace YOUR_CONTAINER with the real container name or ID.
1. Confirm the state and the exit code
docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' YOUR_CONTAINER
If you deploy with Compose, docker compose ps -a lists the project's containers, including stopped ones; the container name is usually <project>-<service>-1.
Exited (1) 8 seconds ago: the main process exited once with code 1.Restarting (1) 3 seconds ago: a restart policy keeps bringing it back, and the number in brackets is the code from the last exit.- The inspect line prints three values: the exit code, whether Docker recorded an out-of-memory kill (
true/false), and Docker's own error message. Keep them apart; they answer different questions. State.Erroris filled mostly when Docker itself couldn't start the process (bad command, port already allocated, and so on). It is empty for most application crashes, so empty does not mean healthy.- A status of
Createdmeans the container was created but never ran. The problem is usually in the run command or image, not in your code.
To see how long the process actually ran and whether a restart policy is involved:
docker inspect --format 'started={{.State.StartedAt}} finished={{.State.FinishedAt}} restarts={{.RestartCount}} policy={{.HostConfig.RestartPolicy.Name}}' YOUR_CONTAINER
A few seconds between started and finished is the "exits immediately after deploy" pattern. These timestamps are in UTC (they end in Z); convert before comparing them with your deploy time or with host logs in local time.
What this does not tell you: why the process exited. It also doesn't confirm you're looking at the right thing, so check that the name and image tag match the deploy you just shipped.
2. Docker exit codes at a glance
| Code | Usual meaning | Details |
|---|---|---|
| 0 | The main process finished successfully | Exit code 0 |
| 1 | Generic application error | Exit code 1 |
| 125 | Docker itself failed to run the container | Exit code 125 |
| 126 | The command was found but couldn't be executed | Exit code 126 |
| 127 | The command couldn't be found | Exit code 127 |
| 137 | Killed with SIGKILL (128 + 9) | Exit code 137 |
| 139 | Segmentation fault, SIGSEGV (128 + 11) | Exit code 139 |
| 143 | Stopped with SIGTERM (128 + 15) | Exit code 143 |
| 2 | Incorrect usage (shell builtins) or an app-specific error | Exit code 2 |
| 132 | Illegal instruction, SIGILL (128 + 4) | Exit code 132 |
| 255 | exit(-1), a failed ssh, or app-defined | Exit code 255 |
Codes above 128 generally mean "killed by signal (code − 128)". kill -l 137 in bash prints KILL; try it for any code you don't recognize. Any other number is whatever the application chose to return, so its logs or documentation decide what it means.
3. What each exit code means, and what to check next
Exit code 0: the main process finished successfully
The container did what its command told it to do and ended without an error. For a migration or backup job, 0 is the expected result. A web service that exits 0 usually started itself in the background (a daemon mode flag, or a script that launches the server with & and returns), or its command was a one-shot task. Check what the container is told to run:
docker inspect --format 'entrypoint={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}}' YOUR_CONTAINER
What it does not prove: that anything is wrong with your code, or that the service is fine. It only says the main process ended without an error.
Exit code 1: generic application error
Most runtimes exit 1 for any uncaught exception or failed startup check. Read the logs (step 4) and find the first error, then compare with what changed in this deploy: image tag, environment variables, config, migrations.
What it does not prove: which error it was. The number is the same for a missing setting, a refused database connection or a syntax error.
Exit code 125: Docker could not run the container
The docker run command or the daemon rejected the request, so your process usually never started. Read the error printed by docker run / docker compose up in the CI or deploy log, and State.Error from step 1. Typical messages: unknown flag, image pull denied, port already allocated (then sudo ss -ltnp shows who holds the port).
125, 126 and 127 can come from two places. When Docker couldn't start the process, they are the exit status of the docker run command itself: you see them in the CI or deploy log, the container usually stays Created, and State.Error holds the message (after a 125, the container's own ExitCode in docker inspect may show a different value, such as 128). When a shell or entrypoint script inside a running container hits the same problem, the container itself exits with 126 or 127 and the message is in docker logs.
What it does not prove: an application bug.
Exit code 126: command found but not executable
Check the configured command (the docker inspect line under exit code 0) and the file's permissions and format inside the image. A script on a bind mount keeps the host file's permissions, so a missing execute bit on the host shows up here. Also compare the image's platform with the host's:
docker image inspect --format '{{.Os}}/{{.Architecture}}' YOUR_IMAGE
uname -m
A mismatch (for example linux/arm64 against x86_64) usually shows up in the logs as exec format error.
What it does not prove: that the file is missing. 126 is "can't execute", 127 is "can't find".
Exit code 127: command not found
The program you meant to run never started. Check the configured command, then confirm the binary exists in this image and on its PATH. A slimmer base image or a typo in Compose command: is a common cause. A shell inside the container also exits 127 when a command in a script isn't found.
What it does not prove: a crash after startup.
Exit code 137: killed with SIGKILL
137 is 128 + 9: something sent SIGKILL. Check OOMKilled from step 1. true makes memory the lead hypothesis; false points to docker kill, a docker stop that ran out its grace period, or another process on the host. 137 alone is not proof of an out-of-memory kill. For the full check (kernel log, memory limits, docker events), see Exit code 137 and OOMKilled.
Exit code 139: segmentation fault (SIGSEGV)
Exit code 139 means the container's main process was killed by signal 11 (SIGSEGV). When a process dies from a signal, Docker records 128 plus the signal number in State.ExitCode: 128 + 11 = 139. SIGSEGV is a segmentation fault: the kernel stopped the process after it accessed a memory address it was not allowed to use.
Common sources are a fault in native code: the application binary, a native library it loads, or a library that does not match the base image. The exit code does not name the function or the library. An illegal instruction is exit code 132 (SIGILL), not 139.
How to check, read-only:
docker inspect --format '{{.State.ExitCode}} {{.State.FinishedAt}}' YOUR_CONTAINER
sudo dmesg -T | grep -i segfault | tail -n 20
docker logs --timestamps YOUR_CONTAINER 2>&1 | tail -n 40
State.ExitCode should print 139. A kernel line that contains segfault and a program name counts as evidence for this exit when its time matches FinishedAt (UTC). dmesg -T prints host local time, and that conversion can drift if the machine was suspended. The kernel rate-limits these lines, so a missing line does not prove there was no fault. docker logs may stop at the crash with no application error when the process dies in native code.
What it does not prove: which file, library, or line caused the fault.
Exit code 143: stopped with SIGTERM
143 is a normal stop request. Find out who asked it to stop: a redeploy, docker stop, docker compose down/up recreating it, a host shutdown, or an orchestrator. docker events and your deploy timeline usually answer this. Docker only keeps recent events (the last 256), so run it soon after the incident:
docker events --since 1h --until "$(date +%s)" --filter container=YOUR_CONTAINER
What it does not prove: a crash. The real question is who sent it and whether the replacement container came up.
Exit code 2: incorrect usage or an app-specific error
Bash builtins return 2 for incorrect usage, generally an invalid option or a missing argument, so an entrypoint script can exit 2 for that reason. Many other programs also use 2 for their own errors; read the logs.
Exit code 132: illegal instruction (SIGILL)
132 is 128 + 4. Signal 4 is SIGILL, "illegal instruction": the CPU refused an instruction in the program. A known cause is a binary built for CPU features the host or VM doesn't provide; for example, MongoDB 5.0 requires the AVX instruction set on x86_64, and on CPUs without it the server stops with Illegal instruction. grep -m1 -o -w avx /proc/cpuinfo prints avx if the CPU has it.
Exit code 255: exit(-1), a failed ssh, or an app-defined error
Only the lowest 8 bits of an exit status reach the parent process, so a program that calls exit(-1) shows up as 255. ssh also exits 255 when ssh itself fails, so a container whose command or script ends with a failed ssh exits 255. Otherwise 255 is whatever the application means by it; read the logs.
4. Read the logs of the exited container and find the first error
docker logs --since 30m --timestamps YOUR_CONTAINER 2>&1 | head -n 80
docker logs --since 30m --timestamps YOUR_CONTAINER 2>&1 | grep -n -i -E 'error|fatal|panic|exception|denied|not found|refused' | head -n 20
docker logsworks on a stopped container until the container is removed. A container started withdocker run --rmtakes its logs with it.--sincealso accepts a timestamp such as2026-09-29T14:05:00(read as local time unless it ends inZ), so you can start just before the deploy. With Compose,docker compose logs --since 30m --timestamps SERVICEdoes the same per service.2>&1matters:docker logspasses the container's stderr through as stderr, and most errors live there, so without itheadandgrepmiss them.- Read the first error after the deploy, not only the last line. If the container restarted several times, the same failure repeats, and the lines just before the first one usually carry the real clue.
- Empty output doesn't clear the app. It may log to a file inside the container, or the logging driver may not make logs available to
docker logs.
First errors that come up often (each is still a hypothesis until you check it):
connection refused/could not connect: a dependency isn't running or the address is wrong. Inside a container,localhostis the container itself, not another service.permission denied: file ownership on mounts, or the image's runtime user.no such file or directoryfor a script that clearly exists: often Windows (CRLF) line endings on the script's first line, or an interpreter the image doesn't have. On the machine where you build the image, check the script without running it:
bash -n entrypoint.sh
grep -c $'\r' entrypoint.sh
bash -n only parses the script and reports syntax errors (use sh -n for a plain #!/bin/sh script). grep -c prints how many lines contain a carriage return; 0 means the line endings are fine.
exec format error: the image was built for a different CPU architecture (see exit code 126).- A missing environment variable or config key: compare key names with the last working deploy. Don't print secret values.
Before you paste logs into a chat, a ticket or an AI prompt, redact passwords, tokens, connection strings, customer emails and internal addresses.
Doing this in OpsMate
OpsMate (itops.sh) puts an SSH terminal and an AI assistant on the same server page. You can type the docker ps, docker inspect and docker logs commands above yourself, which is usually fastest for the exit code. You can also describe the problem in plain language, for example "find out why YOUR_CONTAINER exits after the deploy and summarize the first errors in its logs". The AI proposes troubleshooting commands, and beyond logs it can use docker, journalctl, ps, df and ss for checks. The commands and output stay in the terminal so you can check it against the raw lines. Commands that fail the safety check are blocked and never run. Low-risk fixes run automatically by default, and every step is logged. If the logs contain customer data or secrets, run the commands yourself and share only a redacted excerpt.
Boundaries
- An exit code is a clue, not a diagnosis. The same number has several possible causes, especially 1 and 137. Base a conclusion on the code, the log lines and matching timestamps together.
- The commands in this guide don't change your containers. The AI is mainly for troubleshooting. Commands that fail the safety check are blocked and never run. Low-risk fixes run automatically by default, and every step is logged. Rolling back the image, editing Compose files, changing restart policies or raising memory limits are changes you decide on; plan each one with a way to roll back. For what OpsMate does and doesn't do on its own, see the FAQ.
- An AI summary is a starting point. Check it against the inspect output and the log timestamps.
- If you can't SSH into the host, OpsMate can't reach it either. Start with your cloud provider's console.
Illustrative example
Illustrative example (not a real customer case): after switching the image to a slimmer base, docker ps -a shows Restarting (127) 4 seconds ago. docker inspect prints 127 false with an empty error, so Docker started the process and it's not a memory kill. started and finished are about a second apart. The first line of docker logs --since 15m --timestamps reads /app/start.sh: 5: exec: gunicorn: not found: the entrypoint script runs, but the new base image doesn't include the app server. Changing the restart policy or adding memory would not help. The next step is a decision for a person: roll back to the previous image tag, or rebuild with the dependency installed, and then watch whether the container stays up.
AI diagnostic prompt
A container on this server exits a few seconds after deploy. Without changing anything, get its State.ExitCode, OOMKilled, Error, StartedAt, FinishedAt and restart count, summarize the first errors in its logs since the deploy with timestamps, and tell me what that exit code usually means and what it does not prove. Separate confirmed facts from hypotheses and list what is missing. Do not restart or remove containers, change restart policies, edit Compose files or change memory limits. If a change is needed, propose the smallest step with its risks, how to verify it and how to roll it back, and wait for my approval.
Next checks
- Container stuck in
Restarting? Docker container keeps restarting covers restart policies, backoff, healthchecks and dependencies that aren't ready. - Exit code 137 or
OOMKilled=true? Container exited with code 137: out of memory or something else? - Container runs but the site returns 502? Nginx 502 Bad Gateway: find the cause from the error.log line.
- Logs mention a full disk? Docker logs filling your disk.
- Want the terminal and AI side by side? AI and SSH commands in one workspace.
Try OpsMate
500 free AI calls per month and unlimited servers. The desktop app keeps your SSH credentials on your own machine by default.
FAQ
Why does my Docker container exit immediately after starting?
A container exits as soon as its main process ends. Run docker ps -a to see the exit code and docker logs YOUR_CONTAINER to find the first error after the deploy, not just the last line. A few seconds between StartedAt and FinishedAt in docker inspect is the "exits immediately" pattern. A web service that exits with 0 usually put itself in the background, or its command was a one-shot task.
What do Docker exit codes 1, 125, 126 and 127 mean?
Exit code 1 is a generic application error: a missing setting, a refused database connection or a syntax error all look the same, so read the first error in the logs. 125 means Docker itself couldn't run the container, for example an unknown flag, a denied image pull or a port already allocated. 126 means the command was found but couldn't be executed, usually because it lacks execute permission or was built for a different CPU architecture. 127 means the command couldn't be found, often after switching to a slimmer base image.
What do exit codes 139, 143 and other codes above 128 mean?
Codes above 128 generally mean the process was killed by a signal: subtract 128 to get the signal number, or run kill -l 139 in bash to print its name. 139 is a segmentation fault (SIGSEGV), so check sudo dmesg -T | grep -i segfault for a kernel line naming the binary. 143 is a normal stop with SIGTERM; find out who asked it to stop, such as a redeploy, docker stop or a host shutdown.
Does Docker exit code 137 mean out of memory?
Not necessarily. 137 is 128 + 9: something sent SIGKILL. Check OOMKilled in docker inspect. true makes memory the lead hypothesis; false points to docker kill, a docker stop that ran out its grace period, or another process on the host. For the full check, see "Exit code 137 and OOMKilled".
Need help interpreting the evidence?
OpsMate (itops.sh) helps developers and operators investigate with AI, and you review the evidence yourself. Each time you ask the AI for help, recent terminal output is sent to the cloud AI along with your message, so remove sensitive information first.
Start free Desktop with local credentials