Troubleshooting Docker Out of Memory (OOM) on Ubuntu 22.04

This guide addresses common causes and provides direct solutions for Docker Out of Memory (OOM) issues on Ubuntu 22.04.

1. The Root Cause

Docker OOM errors on Ubuntu 22.04 typically occur when the host system exhausts its available RAM and swap space. This leads the kernel’s OOM killer to terminate Docker daemon processes or containers, impacting service availability and system stability.

2. Quick Fix (CLI)

Increasing the system’s swap file size is a direct mitigation for host-level memory exhaustion.

# Check current swap status
sudo swapon --show

# Create a 4GB swap file (adjust size as needed, e.g., 8G)
sudo fallocate -l 4G /swapfile

# Set appropriate permissions for the swap file
sudo chmod 600 /swapfile

# Set up the swap area
sudo mkswap /swapfile

# Enable the swap file
sudo swapon /swapfile

# Make the swap file persistent across reboots by adding it to /etc/fstab
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# Verify the new swap space
sudo swapon --show
sudo free -h

3. Configuration Check

To prevent future OOM issues caused by resource mismanagement, configure Docker’s daemon settings and enforce container-specific memory limits.

File to Edit: /etc/docker/daemon.json

Changes: Edit or create /etc/docker/daemon.json to include log rotation settings. While not directly preventing RAM OOM, uncontrolled log file growth can consume disk space, indirectly leading to system instability and affecting overall resource availability.

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Explanation: This configures the json-file logging driver to limit each container’s log file size to 10MB and retain a maximum of 3 log files (totaling 30MB per container).

Crucial Preventative Measure: For individual containers, always define memory limits during container creation using the -m or --memory flag with docker run, or the mem_limit directive in docker-compose.yml. This prevents a single misbehaving container from consuming all host memory.

Example for docker run: docker run -d --name my-app --memory="512m" --memory-swap="1g" my-image

Example for docker-compose.yml:

version: '3.8'
services:
  my-app:
    image: my-image
    mem_limit: 512m
    memswap_limit: 1g

After modifying /etc/docker/daemon.json, restart the Docker daemon:

sudo systemctl restart docker

4. Verification

Verify that the system’s memory and Docker daemon configurations have been applied.

# Verify new swap space is active
sudo swapon --show
sudo free -h

# Verify Docker daemon is running and has reloaded configurations
sudo systemctl status docker

# Verify the log rotation settings are active in the daemon configuration
sudo docker system info | grep 'Logging Driver'
sudo docker system info | grep 'Log Options'

# For a specific running container, verify its memory limits (if set)
# Replace <container_name_or_id> with your container's name or ID
sudo docker inspect <container_name_or_id> --format '{{.HostConfig.Memory}} ({{.HostConfig.MemorySwap}})'