# Docker Errors Runtime

> >

- **Type:** Skill
- **Install:** `agentstack add skill-impertio-studio-docker-claude-skill-package-docker-errors-runtime`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Impertio-Studio](https://agentstack.voostack.com/s/impertio-studio)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** https://github.com/Impertio-Studio/Docker-Claude-Skill-Package/tree/main/skills/source/docker-errors/docker-errors-runtime

## Install

```sh
agentstack add skill-impertio-studio-docker-claude-skill-package-docker-errors-runtime
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# docker-errors-runtime

## Quick Reference

### Exit Code Reference

| Exit Code | Signal | Meaning | Common Cause |
|-----------|--------|---------|--------------|
| 0 | — | Success | Container completed normally |
| 1 | — | Application error | Uncaught exception, failed assertion, general error |
| 125 | — | Docker daemon error | Container failed to start (invalid config, missing image) |
| 126 | — | Command not executable | Permission denied on entrypoint/cmd binary |
| 127 | — | Command not found | Binary missing in image, wrong PATH, typo in CMD |
| 137 | SIGKILL (9) | Killed | OOM killer, `docker kill`, or `docker stop` timeout |
| 139 | SIGSEGV (11) | Segmentation fault | Native library crash, memory corruption |
| 143 | SIGTERM (15) | Graceful termination | `docker stop` (process handled SIGTERM) |

### Critical Warnings

**NEVER** ignore exit code 137 — it ALWAYS indicates the container was forcefully killed. Check OOM events with `docker inspect` and `dmesg` before increasing memory limits blindly.

**NEVER** use `--oom-kill-disable` without setting a memory limit (`-m`) — the container can consume ALL host memory and crash the entire system.

**NEVER** assume a container that exits with code 0 is healthy — it may have completed a one-shot command instead of running as a long-lived service. ALWAYS verify the process runs in the foreground.

**ALWAYS** check `docker logs` before any other debugging step — 90% of runtime issues are explained in the application output.

**ALWAYS** use `docker inspect --format='{{.State.ExitCode}}'` to get the exact exit code — `docker ps -a` truncates status information.

---

## Debugging Workflow

### Step 1: Check Logs

```bash
# Last 100 lines
docker logs --tail 100 

# Follow live output with timestamps
docker logs -f -t 

# Logs from last 5 minutes
docker logs --since 5m 
```

### Step 2: Inspect Container State

```bash
# Exit code and error message
docker inspect --format='{{.State.ExitCode}}' 
docker inspect --format='{{.State.Error}}' 

# OOM killed?
docker inspect --format='{{.State.OOMKilled}}' 

# Full state as JSON
docker inspect --format='{{json .State}}'  | jq .
```

### Step 3: Exec Into Running Container

```bash
# Interactive shell (if container is still running)
docker exec -it  sh
docker exec -it  bash

# Check filesystem, processes, network
docker exec  ps aux
docker exec  df -h
docker exec  cat /etc/resolv.conf
```

### Step 4: Check System Events

```bash
# Events for specific container in last 10 minutes
docker events --since 10m --filter container=

# OOM events specifically
docker events --filter event=oom --since 1h

# All die events
docker events --filter event=die --since 1h
```

### Step 5: Resource Usage

```bash
# Live resource stats
docker stats 

# Single snapshot
docker stats --no-stream 

# System-wide disk usage
docker system df -v
```

---

## Runtime Error Diagnostic Table

### Container Exits Immediately (Exit Code 0 or 1)

| Symptom | Cause | Fix |
|---------|-------|-----|
| Container exits with code 0 instantly | Main process runs in background (daemonizes) | ALWAYS run the process in foreground mode. For nginx: `CMD ["nginx", "-g", "daemon off;"]` |
| Container exits with code 0 instantly | CMD is a shell command that completes | Use a long-running process. For shell scripts: end with `exec` or `tail -f /dev/null` for debugging |
| Container exits with code 1 | Application startup failure | Check `docker logs`. Fix config, missing env vars, or dependency issues |
| Container exits with code 1 | Missing environment variables | ALWAYS pass required env vars: `docker run -e DB_HOST=db -e DB_PORT=5432` |

### OOM Killed (Exit Code 137)

| Symptom | Cause | Fix |
|---------|-------|-----|
| `OOMKilled: true` in inspect output | Container exceeded memory limit | Increase limit: `docker run -m 1g`. Profile actual usage with `docker stats` first |
| Exit 137 but `OOMKilled: false` | `docker stop` timeout exceeded (SIGKILL after grace period) | Increase stop timeout: `docker stop -t 30`. Or fix application to handle SIGTERM faster |
| Exit 137 but `OOMKilled: false` | Manual `docker kill` | Check who/what killed the container via `docker events` |
| Host OOM killer triggers | No memory limit set, host runs out of RAM | ALWAYS set memory limits in production: `-m 512m` |

### Permission Denied

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Permission denied` on volume files | UID/GID mismatch between host and container | Match UIDs: `docker run -u $(id -u):$(id -g)`. Or `chown` in Dockerfile |
| `Permission denied` executing entrypoint | Script lacks execute permission | Add in Dockerfile: `RUN chmod +x /entrypoint.sh` |
| `Permission denied` binding to port  1024, or add `--cap-add NET_BIND_SERVICE` |
| `Operation not permitted` on system call | Missing Linux capability | Add specific capability: `--cap-add SYS_PTRACE` for debugging. NEVER use `--privileged` |

### Port Already in Use

| Symptom | Cause | Fix |
|---------|-------|-----|
| `port is already allocated` | Another container using the same host port | Find it: `docker ps --format "{{.Names}}: {{.Ports}}"`. Stop or remap |
| `bind: address already in use` | Host process using the port | Find process: `lsof -i :PORT` or `ss -tlnp \| grep PORT`. Stop it or use different port |
| Port conflict after restart | Old container not removed | Use `--rm` flag, or `docker rm -f ` before starting |

### Exec Format Error

| Symptom | Cause | Fix |
|---------|-------|-----|
| `exec format error` | Architecture mismatch (e.g., ARM image on x86) | Build for correct platform: `docker buildx build --platform linux/amd64`. Or pull correct image: `docker pull --platform linux/amd64 nginx` |
| `exec format error` on shell script | Missing shebang (`#!/bin/sh`) in entrypoint script | ALWAYS add shebang as first line of entrypoint scripts |
| `exec user process caused: no such file or directory` | CRLF line endings in shell script | Convert to LF: `RUN sed -i 's/\r$//' /entrypoint.sh` or use `dos2unix`. ALWAYS use LF in Dockerfiles and scripts |
| `exec user process caused: no such file or directory` | Dynamically linked binary in scratch/distroless image | Build with `CGO_ENABLED=0` for static linking, or use alpine base |

### Read-Only Filesystem

| Symptom | Cause | Fix |
|---------|-------|-----|
| `Read-only file system` write error | Container started with `--read-only` | Add tmpfs for writable paths: `--tmpfs /tmp --tmpfs /run`. Or mount a volume for data directories |
| Application fails to write temp files | Read-only root FS without tmpfs | Map writable paths: `--read-only --tmpfs /tmp:size=64m --mount type=volume,src=data,dst=/app/data` |
| Log file write failure | Read-only FS, app writes to file instead of stdout | Redirect logs to stdout, or mount a volume for log directory |

### PID Limit and Resource Exhaustion

| Symptom | Cause | Fix |
|---------|-------|-----|
| `cannot allocate memory` inside container | Memory limit reached | Increase `-m` limit or optimize application memory usage |
| `fork: Resource temporarily unavailable` | PID limit exceeded | Increase `--pids-limit`. Default is unlimited; set to 200-500 for most apps |
| `no space left on device` | Container writable layer full, or host disk full | Check `docker system df`. Prune unused resources: `docker system prune`. Write data to volumes, not container layer |
| Container extremely slow | CPU throttling | Check `docker stats` for CPU%. Increase `--cpus` limit |

---

## docker inspect for Debugging

### Essential Inspect Commands

```bash
# Full state overview
docker inspect --format='{{json .State}}'  | jq .

# Why did it stop?
docker inspect --format='ExitCode={{.State.ExitCode}} OOM={{.State.OOMKilled}} Error={{.State.Error}}' 

# What command is it running?
docker inspect --format='Entrypoint={{.Config.Entrypoint}} Cmd={{.Config.Cmd}}' 

# Environment variables
docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' 

# Mount points
docker inspect --format='{{range .Mounts}}{{.Type}}: {{.Source}} -> {{.Destination}} ({{if .RW}}rw{{else}}ro{{end}}){{println}}{{end}}' 

# Network settings
docker inspect --format='{{range $net, $config := .NetworkSettings.Networks}}{{$net}}: {{$config.IPAddress}}{{println}}{{end}}' 

# Resource limits
docker inspect --format='Memory={{.HostConfig.Memory}} CPUs={{.HostConfig.NanoCpus}} PidsLimit={{.HostConfig.PidsLimit}}' 

# Health check status
docker inspect --format='{{.State.Health.Status}}' 
docker inspect --format='{{json .State.Health}}'  | jq .

# Restart count
docker inspect --format='RestartCount={{.RestartCount}}' 
```

---

## Decision Trees

### Container Won't Start

```
Container won't start
├─ Exit 125 → Docker daemon error
│  ├─ "invalid reference format" → Fix image name/tag
│  ├─ "no such image" → Pull image first: docker pull 
│  └─ "invalid mount config" → Fix volume/mount syntax
├─ Exit 126 → Command not executable
│  ├─ Check file permissions → chmod +x
│  └─ Check binary format → file 
├─ Exit 127 → Command not found
│  ├─ Typo in CMD/ENTRYPOINT → Fix spelling
│  ├─ Binary not in PATH → Use absolute path
│  └─ Binary not installed → Add to Dockerfile
└─ Exit 0/1 instantly → See "Container Exits Immediately" table
```

### Container Crashes After Running

```
Container was running, then died
├─ Exit 137 → Killed
│  ├─ OOMKilled=true → Memory limit too low (see OOM section)
│  ├─ OOMKilled=false, after docker stop → Stop timeout too short
│  └─ OOMKilled=false, unexpected → Check docker events + dmesg
├─ Exit 139 → Segfault
│  ├─ Native library issue → Check library compatibility
│  └─ Memory corruption → Debug with --cap-add SYS_PTRACE
├─ Exit 143 → Graceful SIGTERM
│  └─ Expected from docker stop → Normal shutdown
└─ Exit 1 → Application error
   └─ Check docker logs → Fix application bug
```

---

## Reference Links

- [references/diagnostics.md](references/diagnostics.md) -- Complete error-to-solution mapping for all runtime errors
- [references/examples.md](references/examples.md) -- Step-by-step debugging sessions with real commands
- [references/anti-patterns.md](references/anti-patterns.md) -- Runtime configuration mistakes and how to avoid them

### Official Sources

- https://docs.docker.com/engine/daemon/troubleshoot/
- https://docs.docker.com/reference/cli/docker/container/run/
- https://docs.docker.com/reference/cli/docker/container/logs/
- https://docs.docker.com/reference/cli/docker/inspect/
- https://docs.docker.com/reference/cli/docker/system/events/

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Impertio-Studio](https://github.com/Impertio-Studio)
- **Source:** [Impertio-Studio/Docker-Claude-Skill-Package](https://github.com/Impertio-Studio/Docker-Claude-Skill-Package)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-impertio-studio-docker-claude-skill-package-docker-errors-runtime
- Seller: https://agentstack.voostack.com/s/impertio-studio
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.