🚨 Docker Error Guide: 'cannot allocate memory' — Fix Container Memory Failures

Overview

cannot allocate memory is the kernel’s ENOMEM surfacing through Docker. It appears when the daemon, the container runtime, or the process inside a container asks the kernel for memory (or a new process/thread) and the request cannot be satisfied. It is distinct from an OOM kill (exit 137): here the allocation fails outright rather than a running process being reaped.

The literal message shows up in several places — starting a container, forking inside one, or during a build:

docker: Error response from daemon: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error setting cgroup config for procHooks process: cannot allocate memory: unknown.

It also appears as a runtime failure inside the container:

fork: retry: Resource temporarily unavailable
runtime: cannot allocate memory

Symptoms

• docker run or docker start fails immediately with cannot allocate memory before the app logs anything.
• Processes inside a running container fail to fork or mmap, logging cannot allocate memory or Resource temporarily unavailable.
• Builds fail at a memory-hungry RUN step (compilers, JVM, webpack).
• The host shows high memory or swap usage in free -h, or the container has a tight --memory limit.
• dmesg shows page allocation failure or cgroup memory events.

Common Root Causes

• Host memory/swap exhaustion — the node genuinely has no free RAM or swap left to hand out.
• Container cgroup memory limit too low — --memory/mem_limit is set below what the app needs, so the cgroup allocator refuses the request.
• Memory overcommit disabled or constrained — vm.overcommit_memory=2 with a low overcommit_ratio makes the kernel refuse allocations that would normally be lazily granted.
• PID/thread limit reached — --pids-limit or the host’s kernel.pid_max/threads-max is hit, so fork fails with the same message.
• Address-space or ulimit caps — a low ulimit -v (virtual memory) or memlock limit blocks large allocations.
• kernel memory / cgroup v1 kmem accounting bugs — older kernels leak kmem accounting, eventually refusing allocations.

Diagnostic Workflow

Start at the host level — is memory actually exhausted?

free -h
cat /proc/meminfo | grep -i 'MemAvailable\|SwapFree\|Commit'
dmesg -T | grep -i 'allocation failure\|out of memory\|oom'

Check the container’s memory limit and current usage:

docker stats --no-stream
docker inspect --format '{{.HostConfig.Memory}} {{.HostConfig.MemorySwap}} {{.HostConfig.PidsLimit}}' <container>

Inspect kernel overcommit policy — a common silent cause on tuned hosts:

sysctl vm.overcommit_memory vm.overcommit_ratio

Check PID/thread ceilings if the failure is on fork:

sysctl kernel.pid_max kernel.threads-max
cat /sys/fs/cgroup/pids/docker/<id>/pids.max 2>/dev/null

Read the daemon’s view of the failure:

journalctl -u docker --since '10 min ago' | grep -i 'cannot allocate\|enomem\|oci runtime'

Example Root Cause Analysis

A Java service failed to start on a 4 GB node with:

OCI runtime create failed: ... cannot allocate memory: unknown

free -h showed 3.1 GB used and no swap. docker inspect revealed --memory=3g, but three other containers were already running. The host was overcommitted at container-create time, so the runtime’s own cgroup setup allocation failed before the JVM even launched.

The fix was twofold: reduce the JVM’s requested heap and container limit to fit the node (--memory=1500m with -XX:MaxRAMPercentage=75), and add a small swap file plus set vm.overcommit_memory=1 so transient allocations succeed. After freeing headroom, the container started cleanly and docker stats showed steady usage well under the limit.

Prevention Best Practices

• Right-size limits to the host. The sum of container --memory limits should leave headroom for the kernel and daemon; do not overcommit tight nodes.
• Configure swap deliberately. A modest swap file absorbs transient spikes and prevents hard allocation failures, though it should not mask undersized RAM.
• Set sane overcommit. vm.overcommit_memory=1 (heuristic) is the safe default for most container hosts; only use strict mode (2) with a well-chosen ratio.
• Cap PIDs, but not too low. Use --pids-limit to prevent fork bombs, but set it high enough for the app’s real thread/process count.
• Monitor MemAvailable and swap, and alert before the host runs dry rather than after allocations start failing.
• Prefer modern cgroup v2 kernels to avoid legacy kmem accounting leaks.

Quick Command Reference

free -h                                            # host memory + swap
docker stats --no-stream                           # per-container usage
docker inspect --format '{{.HostConfig.Memory}}' c # container mem limit
sysctl vm.overcommit_memory vm.overcommit_ratio    # overcommit policy
sysctl kernel.pid_max kernel.threads-max           # fork ceilings
dmesg -T | grep -i 'allocation failure'            # kernel allocation errors
docker run --memory=1500m --memory-swap=2g img     # explicit limits

Conclusion

cannot allocate memory means an allocation — of RAM, address space, or a new process — was refused, not that a process was OOM-killed. Work outward from the host: confirm real free memory and swap, then check the container’s cgroup limit, overcommit policy, and PID ceilings. Right-size limits to the node, give the host a little swap and a sane overcommit policy, and the error disappears. For the related reaping case, see the OOMKilled guide and the broader Docker guides.