Exit code 125 Fatal Docker & Kubernetes

Exit Code 125 (Docker Run Failed) in Docker & Kubernetes

Verdict · 125 = Docker CLI or daemon failure before the container starts

Exit code 125 is produced by the Docker CLI or daemon, not by your process. The container never created a running task: image pull, option parsing, port binding, volume mounting or daemon communication failed. There is no PID 1 to inspect and no application log to read.

Proof commands Root causes Fix configuration Related guides FAQ

Observed exit125

Signal / meaningDocker Run Failed

Default actionFatal

Proof commands: confirm the exit status and the killer

Run these before changing anything. The first two identify what the runtime recorded; the third finds a kernel-level kill on the host. Replace the placeholder container ID, pod name or host path with your own.

Reproduce the start

docker run --rm <image>; echo "exit=$?"

Docker daemon log

journalctl -u docker --since '15 min ago' --no-pager | tail -n 80

Kubernetes events

kubectl describe pod <pod_name> | sed -n '/Events:/,$p'

If docker inspect <id> returns No such object, the container was never created. That is the defining difference between 125 and 126/127: the image or runtime configuration failed before exec, so no command inside the image ran. Fix the start configuration, then look for application errors only after a container exists.

Three production root causes

Docker could not start the container at all. Look at the CLI error text and journalctl -u docker, not application logs. Frequent causes are a host port already in use, an invalid runtime flag or memory floor, a failed registry pull, and a bind mount whose source path is wrong.

1. Host port is already allocated

The daemon reports Bind for 0.0.0.0:80 failed: port is already allocated. Another container, a reverse proxy or a host service owns the port. Check with ss -ltnp 'sport = :80' and docker ps --format '{{.Names}} {{.Ports}}'. A second Compose project that maps the same host port will hit the same allocation error.

2. Invalid runtime option or resource floor

Docker rejects options before start: --memory=4m is below the cgroup minimum (about 6MB), an unknown --runtime, a missing --device path, an invalid --cap-add or a malformed --mount. Compose validates the file and exits non-zero while parsing, without creating a container. docker run exits 125 and the container is never created.

3. Image pull, mount or daemon failure

Private registry credentials, a missing tag, a bind source on a path the daemon cannot read, a full disk, or permission on /var/run/docker.sock all fail before start. Kubernetes shows the equivalent as FailedCreate, FailedMount or ErrImagePull events with the pod still Pending or ContainerCreating.

Copy-ready fixes for Docker Compose and Kubernetes

The two manifests set explicit memory limits and a termination grace period. Use them as a baseline, then adjust the values to the measured working set of the service.

Compose

docker-compose.yml

Docker's minimum memory limit is around 6MB, not zero. Use a realistic limit above the application's working set. Validate the file with docker compose config -q before up; syntax and key errors are reported without starting containers.

services:
  app:
    image: ghcr.io/acme/app:1.4.2
    restart: on-failure:3
    stop_grace_period: 10s
    deploy:
      resources:
        limits:
          memory: 128M
        reservations:
          memory: 64M

Kubernetes

deployment.yaml

In Kubernetes a bad start configuration never reaches exit 125; the container stays Pending or ContainerCreating and the reason is in Events. Keep resources.requests within the node's allocatable memory, and make every referenced Secret, ConfigMap and PVC exist before rollout.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: app
  template:
    metadata:
      labels:
        app: app
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: app
          image: ghcr.io/acme/app:1.4.2
          resources:
            requests:
              cpu: "250m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"

Frequently asked questions

Why is there no container when Docker exits 125?

Because 125 is returned before a container is created. Docker validated the request, failed to pull the image, could not allocate a port or mount, or lost communication with the daemon. Without a container there is no State.ExitCode or application log to inspect.

How do I find which port is blocking Docker?

Run ss -ltnp 'sport = :PORT' on the host and docker ps --format '{{.Names}}\t{{.Ports}}'. If another container owns it, change the host side of the mapping such as 8080:80. Also check that two Compose projects do not publish the same host port.

Does Kubernetes have an exit code 125?

No. Kubernetes does not run the docker CLI and does not synthesize 125 for start failures. A pod that cannot start stays Pending or ContainerCreating with events such as FailedScheduling, FailedMount or ErrImagePull. Exit codes apply only after a container process actually runs.

Follow the status you actually observed, then check the related port or calculator when the failure involves networking, exposure or firewall rules.

Exit Code LibraryAll Linux, Docker and Kubernetes exit codes Exit Code 126 (Cannot Execute)Permissions and architecture mismatches Exit Code 127 (Command Not Found)Missing binaries and Alpine glibc gaps Port 2376 (Docker)Docker TLS API exposure and firewall rules Subnet CalculatorNetwork, broadcast and usable host range Port 30001 (K8s)Kubernetes NodePort exposure and checks

Reference basis: POSIX signal semantics (128 + n), Docker container exit status conventions, and Kubernetes container termination behaviour. Verify the exact behaviour against your runtime version before relying on it in an incident.

Last reviewed 2026-11-06 · All exit codes · Developer tools · Privacy