6.3.4.5 Container OOM Behavior

Container OOM behavior describes what happens when a container's processes attempt to use more memory than its configured limit allows — the kernel's out-of-memory killer selects and terminates a process within the container, typically resulting in the container's main process exiting with a recognizable status.

How the OOM Killer Responds to a Memory Limit Violation

When a container's cgroup-enforced memory limit is exceeded, the kernel's out-of-memory killer intervenes, selecting a process within that container's cgroup to terminate in order to free up memory.

docker run -d --memory=256m myapp:1.0

If this container's processes collectively attempt to exceed 256MB, the kernel kills one or more processes within it to bring usage back under the limit.

Identifying an OOM Kill After the Fact

A container's exit status and metadata directly reveal whether it was terminated specifically due to exceeding its memory limit.

docker inspect myapp --format '{{.State.OOMKilled}} {{.State.ExitCode}}'

OOMKilled reporting true, often paired with exit code 137, confirms this specific cause.

Why the Killed Process Might Not Be the Expected One

Within a container running multiple processes, the kernel's OOM killer selects a victim process based on its own heuristics, which might not necessarily be the process an operator would have expected or preferred to be terminated.

docker exec myapp ps aux

Reviewing what processes were running before an OOM kill can help understand exactly what happened and whether the application's process structure should be reconsidered.

Preventing Repeated OOM Kills

A container repeatedly hitting its memory limit and being OOM-killed signals either a genuine memory leak in the application or a memory limit set too conservatively for its actual normal needs — distinguishing between these two causes is necessary to address the underlying issue.

docker stats myapp

Why Understanding Container OOM Behavior Matters

Recognizing the specific signature of an OOM kill, and understanding what it reveals about a container's actual memory usage relative to its configured limit, is essential for correctly diagnosing and resolving memory-related container failures rather than misattributing them to an unrelated cause.