Docker: Container Exited with Code 137 (OOMKilled)

The exact signal

$ docker ps -a
CONTAINER ID   IMAGE       STATUS
a1b2c3d4e5f6   my-api      Exited (137) 3 minutes ago

$ docker inspect a1b2c3d4e5f6 --format='{{.State.OOMKilled}}'
true

137 is Docker's convention of 128 + signal number, and signal 9 is SIGKILL — an unconditional, un-catchable kill with no chance for the process to clean up. The OOM killer always uses SIGKILL, which is why 137 is strongly associated with memory exhaustion. But it is not the only thing that sends SIGKILL, which is exactly why the confirmation step above matters before you spend time chasing a memory leak that doesn't exist.

Troubleshooting at a glance

The single OOMKilled flag splits this error into two completely different worlds. Start here:

Step 1: confirm it was actually the OOM killer

Don't assume — check. This single flag tells you definitively whether memory was the cause:

docker inspect <container> --format='{{.State.OOMKilled}}'
# true  -> the kernel's OOM killer terminated this container specifically
# false -> SIGKILL came from somewhere else (see "other causes" below)

You can also confirm it at the kernel level. On the Docker host (not inside the container), the OOM killer logs every kill it performs:

dmesg | grep -i "killed process"
# or on systemd hosts:
journalctl -k | grep -i "out of memory"

cgroup v1 vs v2: most current Linux distributions (and Docker Desktop) now default to cgroup v2 rather than the older v1. This doesn't change anything you do on this page — Docker reports OOMKilled: true and the kernel logs the kill identically regardless of the cgroup version. If docker inspect shows the flag, you can trust it either way.

Step 2: figure out which scope ran out — container or host

The same OOM killer operates at two different scopes, and the fix is different for each:

On macOS and Windows the "host" is the Docker Desktop VM, which has its own separate ceiling — see the next section.

Docker Desktop (macOS/Windows): the VM has its own memory ceiling

On macOS and Windows there is no Linux "host" in the usual sense — the daemon and every container run inside a single Docker Desktop VM, and that VM is allocated a fixed slice of your machine's memory. Even a container with no -m limit of its own can't exceed what the VM has, so a memory-hungry container gets OOMKilled the moment the whole VM fills up. Raise the VM's allocation here:

Docker Desktop → Settings → Resources → Advanced → Memory limit

This is one of the most common reasons a container that runs fine in CI or on a Linux server gets OOMKilled only on a developer's Mac or Windows laptop — the default Docker Desktop memory allocation is simply smaller than what the workload needs.

Fix 1: the workload genuinely needs more memory — raise the limit

If usage sits at a stable, predictable working set that's simply higher than your original budget, raising the limit is the correct, complete fix:

# docker run
docker run -m 1g my-api

# docker-compose.yml
services:
  api:
    mem_limit: 1g

# Kubernetes
resources:
  limits:
    memory: "1Gi"

Before raising it, watch the trend with docker stats for a while — a stable plateau near the limit supports "just needs more"; a line that keeps climbing without leveling off supports "leak" (Fix 3), and a higher limit there just delays the identical crash.

Fix 2: runtime heap sizing that ignores the container limit

Several language runtimes historically sized their default heap from the host's total memory, not the container's cgroup limit — a container capped at 512MB but running on a 64GB host would happily try to grow a multi-gigabyte heap and get OOMKilled almost immediately.

# Java (JDK 10+ has UseContainerSupport on by default, but pin it explicitly):
java -XX:MaxRAMPercentage=75.0 -jar app.jar
# leaves ~25% headroom for thread stacks, metaspace, and off-heap buffers

# Node.js — the V8 heap default also isn't container-aware:
node --max-old-space-size=384 server.js   # for a 512MB container limit

# Python — no heap flag as such, but cap worker count so total RSS fits:
gunicorn --workers=2 --max-requests=1000 --max-requests-jitter=100 app:app

The Node and Java flags above are deliberately set below the container's memory limit, not equal to it — thread stacks, native buffers, and the runtime's own bookkeeping all need headroom outside whatever number you hand to -Xmx or --max-old-space-size.

Fix 3: it's a genuine memory leak

If memory climbs steadily over hours or days instead of leveling off at a working set, no limit is generous enough — you're watching a leak, and it will eventually hit any ceiling you set. Confirm the trend and then look at what's actually accumulating:

# watch live, container-scoped memory over time
docker stats <container>

# Node: a leak often shows as a growing heap even after forced GC —
# take two heap snapshots an hour apart and diff them in Chrome DevTools

# Python: common culprits are a growing in-memory cache/list with no eviction,
# or objects held by closures/listeners that are never unregistered

A pragmatic stopgap while you track down the real leak: recycle worker processes periodically (gunicorn --max-requests, PM2's max_memory_restart) so accumulated memory gets released on a schedule instead of crashing unpredictably in production.

How this looks in Kubernetes

Same mechanism, different vocabulary. A pod hitting its memory limit shows up like this:

$ kubectl describe pod my-api-7d4f9c
Last State:   Terminated
  Reason:     OOMKilled
  Exit Code:  137

Kubernetes distinguishes this from eviction: when the whole node is under memory pressure, the kubelet can proactively remove entire pods (lowest-priority/most-over-limit first) before the kernel OOM killer would even trigger. That shows Reason: Evicted, not OOMKilled — a node-level capacity problem rather than one pod exceeding its own limit, and it needs more cluster capacity or better resource requests/limits across pods, not just a bigger number on this one deployment.

When 137 is NOT about memory

Because 137 only encodes "received SIGKILL," a few other things produce it identically — and OOMKilled: false from Step 1 tells you decisively that you're in one of these cases instead:

• A docker stop that didn't exit cleanly within its grace period, escalated automatically to docker kill (SIGKILL)
• A failed Docker or Kubernetes healthcheck causing the platform to forcibly kill an unresponsive container
• An operator or script running docker kill <container> directly
• An orchestrator forcefully rescheduling/stopping a container during a deploy or scale-down

Debugging checklist

• ✓ docker inspect --format='{{.State.OOMKilled}}' — true or false, first, before anything else
• ✓ If true: container limit (-m/mem_limit) or whole-host memory? Check both
• ✓ Mac/Windows: is Docker Desktop's own VM memory (Settings → Resources) large enough for the workload?
• ✓ docker stats over time — stable plateau (needs more memory) vs steady climb (leak)?
• ✓ Java: is -Xmx/-XX:MaxRAMPercentage leaving headroom below the container limit?
• ✓ Node: is --max-old-space-size set below the container's memory limit?
• ✓ Kubernetes: kubectl describe pod — "OOMKilled" (this container) or "Evicted" (whole node)?
• ✓ If OOMKilled: false: check for a healthcheck failure, a manual kill, or an orchestrator-triggered stop instead