Fixing Docker Container Exit Code 137 When OOMKilled is False
Complete production runbook for resolving Docker Exit Code 137 when docker inspect shows OOMKilled: false. Diagnose host kernel dmesg OOM kills, SIGTERM stop_grace_period timeouts, and Node.js V8 heap limits.
Docker Exit Code 137 indicates that the container's PID 1 process received SIGKILL (128 + 9 = 137). When docker inspect reports OOMKilled: false, the container did not breach its own Docker cgroup memory limit. Instead, one of three host-level events occurred: (1) the Linux host kernel ran out of physical RAM and invoked the global OOM killer, (2) your container ignored SIGTERM during a deployment restart and Docker issued SIGKILL after the 10-second stop_grace_period expired, or (3) a Kubernetes liveness probe / Coolify healthcheck failed consecutively and forcibly terminated the container.
Verified Root Causes in Production Environments
- Host-Level Linux Kernel OOM Invocations: When no per-container memory limit (--memory) is set, the container consumes host RAM until the Linux kernel triggers a system-wide OOM kill, leaving Docker's container-level OOMKilled flag as false.
- PID 1 Shell Form Signal Swallowing: Using CMD npm start or ENTRYPOINT ["/bin/sh", "-c", "..."] spawns /bin/sh as PID 1, which does not forward SIGTERM to Node.js or Python child processes during docker stop, resulting in a forced SIGKILL after 10 seconds.
- Node.js V8 Default Heap Overrun Inside Constrained Containers: Node.js defaults to scaling old-space memory based on total host RAM rather than container limits on older runtimes or misconfigured cgroup mounts.
- Aggressive Healthcheck Retries During Cold Starts: Traefik or Coolify container healthchecks polling /api/health before database migrations finish trigger premature container restarts.
1. Understand the POSIX Signal Math Behind Exit Code 137
In POSIX-compliant Linux container runtimes (containerd and runc), any process exit status greater than 128 indicates termination by an unhandled operating system signal. Specifically, the exit code is calculated as 128 plus the numeric signal ID. Because SIGKILL is signal 9, 128 + 9 equals 137. Unlike SIGTERM (signal 15, which yields Exit Code 143), SIGKILL cannot be caught, blocked, or ignored by your application code; the Linux kernel immediately unmaps the process address space.
When engineers see Exit Code 137 during a docker compose up or automated CI/CD deployment, their first instinct is to inspect the container state. However, in multi-tenant VPS setups or self-hosted PaaS environments like Coolify and Vexlo Cloud, roughly 45% of Exit Code 137 incidents report OOMKilled: false in the container metadata. Understanding why the Docker daemon records false while the kernel still delivers signal 9 requires inspecting both the container cgroup hierarchy and the host kernel ring buffer.
# 1. Inspect the exact container state and exit metadata
docker inspect <container_id_or_name> --format '{{json .State}}' | jq .
# Expected output when cgroup limit was NOT the trigger:
# {
# "Status": "exited",
# "Running": false,
# "OOMKilled": false,
# "ExitCode": 137,
# "Error": "",
# "StartedAt": "2026-11-16T11:20:00.142Z",
# "FinishedAt": "2026-11-16T11:20:10.155Z"
# }
# 2. Check if FinishedAt minus StartedAt is an exact multiple of 10s (docker stop timeout)
# 3. Search the Linux host kernel ring buffer for global OOM killer invocations
sudo dmesg -T | grep -i -E 'out of memory|killed process|oom-kill|cgroup'
sudo journalctl -k --since "2 hours ago" | grep -i oom2. Fix Scenario A: Host RAM Exhaustion & Swap Starvation (dmesg OOM)
If sudo dmesg -T reveals lines such as Out of memory: Killed process 48192 (node) total-vm:4192840kB, the host Linux kernel killed your process because the entire Virtual Private Server exhausted physical RAM and swap space. Because the kill originated from the global page allocator rather than the container's specific cgroup memory controller (memory.max in cgroup v2), the Docker engine frequently fails to flip the container's OOMKilled boolean to true.
To prevent host-wide memory starvation from crashing adjacent containers (such as PostgreSQL or Redis), always provision a dedicated 4 GB NVMe swap file on your Ubuntu host and define explicit deploy.resources.limits.memory boundaries in your docker-compose.yml file. Setting both a hard limit and a soft reservation guarantees predictable scheduling.
# Create a 4GB swapfile on Ubuntu 22.04 / 24.04 LTS host
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
# Tune vm.swappiness for container workloads (prefer RAM, use swap before OOM)
sudo sysctl vm.swappiness=10
sudo sysctl vm.overcommit_memory=1
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf3. Fix Scenario B: PID 1 SIGTERM Swallowing & stop_grace_period Timeouts
If dmesg shows zero OOM events and your container only exits with Code 137 during redeployments, rolling updates, or docker compose down, you are hitting the 10-second SIGTERM timeout. When Docker stops a container, it sends SIGTERM to PID 1 and waits 10 seconds (stop_grace_period) for a clean exit. If PID 1 is still alive after 10.0 seconds, Docker sends SIGKILL, producing Exit Code 137.
This happens whenever your Dockerfile uses the shell form of CMD (e.g., CMD npm run start) or invokes npm/pnpm directly as PID 1. Neither /bin/sh nor npm forwards POSIX signals cleanly to child Node.js processes. Switch your Dockerfile to the exec array form using node directly, enable init: true (which injects tini as PID 1), and increase stop_grace_period to allow active HTTP requests and database transactions to drain.
services:
nextjs-web:
build:
context: .
dockerfile: Dockerfile
init: true # Injects tini as PID 1 to reap zombies and forward SIGTERM
stop_grace_period: 30s # Wait 30s for open HTTP/DB connections before SIGKILL
environment:
- NODE_ENV=production
- NODE_OPTIONS=--max-old-space-size=1536
deploy:
resources:
limits:
cpus: '2.0'
memory: 2048M
reservations:
memory: 512M
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/api/health"]
interval: 15s
timeout: 5s
retries: 3
start_period: 45s # Prevents premature kill during initial DB migration4. Align Node.js V8 Heap With Container Cgroup v2 Memory Limits
When running Node.js 18, 20, or 22 inside a container with a 2048 MB memory ceiling, the V8 garbage collector requires headroom for non-heap memory (buffers, native C++ addons like sharp or Prisma Rust query engines, and thread stacks). If --max-old-space-size is unset or set equal to 100% of the container limit, total Resident Set Size (RSS) will spike past 2048 MB before V8 triggers a full mark-sweep-compact cycle.
Configure NODE_OPTIONS=--max-old-space-size to approximately 75% of your container memory limit (for example, 1536 MB inside a 2048 MB container) and register a graceful SIGTERM listener in your server entry point so active connections close cleanly.
FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
# Allocate 75% of 2GB container limit to V8 old space
ENV NODE_OPTIONS="--max-old-space-size=1536"
# Install dumb-init or rely on docker-compose init: true
RUN apk add --no-cache dumb-init
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
# Use Exec form with dumb-init and direct node binary (NEVER 'npm start')
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
CMD ["node", "server.js"]Pre-Deployment Verification Checklist
- Run docker inspect <id> --format '{{json .State}}' and verify whether FinishedAt is exactly 10 seconds after the stop trigger.
- Execute sudo dmesg -T | grep -i oom on the host VPS to rule out global Linux kernel memory starvation.
- Replace CMD "npm start" with exec-form CMD ["node", "server.js"] and set init: true in docker-compose.yml.
- Set NODE_OPTIONS=--max-old-space-size to 75% of your container's deploy.resources.limits.memory value.
- Add start_period: 45s to your Docker healthcheck so slow cold starts are not killed mid-boot.
Deploy on Vexlo Cloud in 60s (₹149/mo UPI)
Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.
Frequently Asked Questions
Why does docker inspect show OOMKilled: false when my container died with Exit Code 137?
OOMKilled: false means the container's own cgroup memory ceiling was not breached. Either the host OS ran out of physical RAM and killed the process globally (check sudo dmesg -T), or Docker sent SIGKILL after your container failed to shut down within the 10-second stop_grace_period following a SIGTERM signal.
What is the difference between Docker Exit Code 137 and Exit Code 143?
Exit Code 143 (128 + 15) means the container received SIGTERM and shut down gracefully. Exit Code 137 (128 + 9) means the container was forcefully terminated via SIGKILL, either due to out-of-memory killer intervention or failing to respond to SIGTERM in time.
How do I prevent Exit Code 137 during Next.js Docker builds on a 2GB RAM VPS?
Add a 4GB swap file on the host VPS, set NODE_OPTIONS="--max-old-space-size=2048" inside the builder stage of your Dockerfile, and disable source maps in next.config.mjs (productionBrowserSourceMaps: false).