Docker Container Stuck in Created Status

Threat/Impact Level: MEDIUM | Downtime Risk: HIGH | Time to Fix: 5–15 mins

TL;DR

• What broke: The container was created by the daemon but never transitioned to running — the runtime hit a pre-start failure (bad volume mount, missing network, OOM kill at fork, or a corrupted image layer) before the entrypoint process could be exec'd.
• How to fix it: Run docker inspect <container_id> and docker logs <container_id> immediately. The State.Error field and OOMKilled flag will pinpoint the exact failure class. Fix the offending resource binding or image, then docker rm the dead container and re-run.
• Sandbox: Use our Client-Side Sandbox above to auto-refactor your docker-compose.yml or Dockerfile — paste it in and get a corrected config without sending your secrets anywhere.

CONTAINER ID   IMAGE         COMMAND               CREATED         STATUS    PORTS   NAMES
a3f9c1d82b44   myapp:latest  "tail -f /dev/null"   3 minutes ago   Created           myapp_debug

How to Fix It

Step 1: Get the actual error

# This is the only command that matters first
docker inspect <container_id> --format='{{json .State}}' | jq .

Look for:

• "Error": "<message>" — direct cause
• "OOMKilled": true — host memory exhausted at fork time
• "ExitCode": 128+ — signal-based kill before start

# Also pull daemon-level events
docker events --filter container=<container_id> --since 10m

Step 2: Common root causes and fixes

Cause A: Named volume or bind mount does not exist

# docker-compose.yml
services:
  debug:
    image: myapp:latest
-   volumes:
-     - /host/path/that/doesnt/exist:/app/data
+   volumes:
+     - ./data:/app/data  # ensure host path exists: mkdir -p ./data

Cause B: Network referenced does not exist

# docker-compose.yml
services:
  debug:
    image: myapp:latest
-   networks:
-     - backend_net  # network never declared or pre-created
+   networks:
+     - backend_net
+
+networks:
+  backend_net:
+    driver: bridge

Cause C: Image entrypoint override syntax error

# Dockerfile
- ENTRYPOINT tail -f /dev/null
+ ENTRYPOINT ["tail", "-f", "/dev/null"]
# Shell form does not receive signals correctly and can fail on minimal images
# (e.g., distroless, scratch) that have no /bin/sh

Cause D: Resource constraints killing the container at fork

# docker-compose.yml
services:
  debug:
    image: myapp:latest
    deploy:
      resources:
        limits:
-         memory: 4m   # too low — cgroup OOM fires before tail starts
+         memory: 64m

Basic Fix (one-liner cleanup and restart)

docker rm a3f9c1d82b44
docker inspect myapp:latest --format='{{.Config.Entrypoint}}'
# Verify the image has /usr/bin/tail available
docker run --rm myapp:latest which tail
docker-compose up -d debug

Enterprise Best Practice

Stop using tail -f /dev/null as a keep-alive. It is a footgun. Use a proper init process:

# Dockerfile
- ENTRYPOINT ["tail", "-f", "/dev/null"]
+ RUN apk add --no-cache tini
+ ENTRYPOINT ["/sbin/tini", "--"]
+ CMD ["sleep", "infinity"]
# tini reaps zombie processes, handles SIGTERM correctly,
# and works on distroless/minimal images via multi-stage copy

For debug sidecars in Kubernetes, use ephemeral containers instead of baking a placeholder entrypoint into your image:

kubectl debug -it <pod> --image=busybox:latest --target=<container>

💡 Tired of pasting proprietary infrastructure configs into public LLMs? Generic AI interfaces log your company's ARNs, connection strings, and private keys. StackEngine enforces client-side zero-trust boundaries—the sandbox above executes 100% locally in your browser. Drop your broken manifest above to redact secrets locally and synthesize deterministic patch drafts with your own API key.

(For CI/CD pipeline automation, install via npm i -g stackengine).

# .github/workflows/lint.yml
- name: Lint Dockerfile
  uses: hadolint/hadolint-action@v3.1.0
  with:
    dockerfile: Dockerfile
    failure-threshold: warning
# DL3025 fires on shell-form CMD/ENTRYPOINT

checkov -f docker-compose.yml --check CKV_DOCKER_7,CKV_DOCKER_8

# docker-compose.yml
services:
  debug:
    image: myapp:latest
    healthcheck:
      test: ["CMD", "pgrep", "tail"]
      interval: 5s
      timeout: 3s
      retries: 2
      start_period: 5s
    # Container moves to 'unhealthy' in 16s instead of hanging forever

# policy/docker.rego
package docker

deny[msg] {
  input.Entrypoint[_] == "tail"
  msg := "Placeholder entrypoint 'tail' is not permitted in production images. Use tini or a real process."
}

conftest test docker-inspect-output.json --policy policy/