# Docker Error Patterns

A structured dictionary mapping common Docker error messages to their causes and fixes.
When diagnosing a deployment failure, check this reference first.

## Compose / YAML Errors

### "error decoding ... empty section between colons"
- **Cause**: A volume mapping like `${VAR}:/data` where `$VAR` is empty or unset
- **Fix**: Replace with a literal path: `./data:/data`. Never rely on unset env vars in volume specs

### "env_file[x] expected type 'string', got unconvertible type 'map[string]interface {}'"
- **Cause**: Using modern `env_file` syntax (with `path` and `required` keys) on Docker Compose < v2.24.0.
- **Fix**: Convert the map entries to simple string list items.
  - *Bad:* `- path: .env, required: false`
  - *Good:* `- .env`
  - *Note:* You must also ensure the file exists since you removed `required: false`.

### "yaml: line N: did not find expected key"
- **Cause**: YAML indentation error — tabs instead of spaces, or misaligned keys
- **Fix**: Validate the YAML. Use 2-space indentation consistently. Never use tabs

### "service X has neither an image nor a build context"
- **Cause**: A service definition is missing both `image:` and `build:`
- **Fix**: Add either `image: <name>` to pull a public image, or `build: .` to build locally

### "no configuration file provided: not found"
- **Cause**: No `docker-compose.yml` or `docker-compose.yaml` in the current directory
- **Fix**: Ensure you're running from the right directory, or specify `-f path/to/compose.yml`

## Container Runtime Errors

### "exec format error"
- **Cause**: Binary incompatible with the container's CPU architecture (e.g. amd64 binary on arm64)
- **Fix**: Use a multi-arch image, or build from source on the target architecture

### "OCI runtime exec failed: exec failed: unable to start container process"
- **Cause**: The entrypoint or command binary doesn't exist in the container
- **Fix**: Check the image's available binaries with `docker run --rm <image> ls /usr/local/bin/`

### "standard_init_linux.go: exec user process caused: no such file or directory"
- **Cause**: Shell script has Windows line endings (CRLF) or the shebang binary doesn't exist
- **Fix**: Convert line endings with `dos2unix`, or verify the shebang path (`#!/bin/sh` vs `#!/bin/bash`)

### "MODULE_NOT_FOUND" or "Cannot find module"
- **Cause (Node.js)**: The entrypoint tries to run a command as a Node script. Usually means the wrong entrypoint is set
- **Fix**: Set the correct `entrypoint` in docker-compose.yml (e.g. `entrypoint: ["openclaw"]` instead of the default `node`)

## Network Errors

### "bind: address already in use"
- **Cause**: Another process is using the same port on the host
- **Fix**: `sudo lsof -i :PORT` to find the process, then stop it or change the port mapping

### "could not resolve host"
- **Cause**: DNS failure inside the container
- **Fix**: Restart Docker daemon, or set custom DNS: `dns: [8.8.8.8]`

### "connection refused" (between containers)
- **Cause**: Using `localhost` instead of the service name, or services are on different networks
- **Fix**: Use the service name as hostname (e.g. `http://db:5432`), ensure both services are on the same network

## Volume / Permission Errors

### "EACCES: permission denied" or "Permission denied"
- **Cause**: Container runs as non-root but host directory is owned by root
- **Fix**: `sudo chown -R $(id -u):$(id -g) ./path/to/volume`, or add `user: "1000:1000"` to the service

### "read-only file system"
- **Cause**: Service has `read_only: true` but tries to write outside allowed paths
- **Fix**: Add `tmpfs: [/tmp]` for temporary files, or mount writable volumes for specific paths

### "invalid mount config: invalid spec"
- **Cause**: Volume spec syntax error — missing colon, empty variable, or invalid path
- **Fix**: Use literal paths: `./data:/app/data`. Avoid `${UNSET_VAR}:/path`

## Image / Pull Errors

### "manifest unknown" or "manifest not found"
- **Cause**: The image tag doesn't exist (typo, removed, or architecture mismatch)
- **Fix**: Check Docker Hub for available tags. Use `docker search <image>` to verify

### "no matching manifest for linux/arm64"
- **Cause**: Image doesn't support ARM architecture
- **Fix**: Find an ARM-compatible variant, use Alpine, or build from source

### "denied: requested access to the resource is denied"
- **Cause**: Trying to pull a private image without authentication
- **Fix**: `docker login` first, or check that the image name is spelled correctly

## Resource Errors

### "no space left on device"
- **Cause**: Docker images, containers, or volumes filling the disk
- **Fix**: `docker system prune -af --volumes` — WARNING: deletes all unused data

### "OOM killed" or container exits with code 137
- **Cause**: Container exceeded memory limit or host ran out of memory
- **Fix**: Increase `deploy.resources.limits.memory`, or reduce the app's memory usage. On Raspberry Pi, enable swap
