Troubleshooting Docker Container Exit Code 139: Segmentation Fault on Ubuntu 20.04 LTS

Resolve Docker container segmentation faults (exit code 139) on Ubuntu 20.04 LTS. This guide covers memory limits, application bugs, and system diagnostics to restore service.

A Docker container exiting with code 139 on Ubuntu 20.04 LTS is a critical issue indicating a SIGSEGV or Segmentation Fault. This means the application running inside your Docker container attempted to access a memory location that it was not authorized to access, or tried to access it in an illegal way. This often leads to immediate termination of the process and, consequently, the container itself, resulting in service downtime. As a seasoned Systems Administrator, diagnosing and resolving segfaults within containerized environments requires a systematic approach, examining everything from application code to host system resources.

Symptom & Error Signature

When a Docker container experiences a segmentation fault, it will stop unexpectedly. You won't typically see a graceful shutdown; the container will simply disappear from the active docker ps list. Checking docker ps -a will reveal the Exited (139) status.

Typical terminal output when checking container status:

sudo docker ps -a

CONTAINER ID   IMAGE                 COMMAND                  CREATED          STATUS                       PORTS     NAMES
a1b2c3d4e5f6   my-app-image:latest   "/usr/local/bin/myapp"   10 minutes ago   Exited (139) 9 minutes ago             my-app-container

The docker logs command for the affected container might provide more specific details, although segfaults often prevent the application from logging extensive debug information just before crashing. However, you might find traces of memory errors or backtraces if the application's logging mechanism is robust or if a signal handler was invoked.

sudo docker logs my-app-container

...
[INFO] Application started.
...
Segmentation fault (core dumped)
...

Additionally, the host system's kernel logs (dmesg) can sometimes provide insights, especially if an Out-Of-Memory (OOM) killer was involved or if the kernel recorded the segfault event directly.

sudo dmesg -T | grep -iE 'segfault|oom|memory'

[Sat Sep  5 10:30:15 2026] my-app-container[12345]: segfault at 7f8b9c0d0000 ip 00007f8b9c0d0000 sp 00007ffe04b2c340 error 14 in libsomething.so[7f8b9c0cf000+1000]
[Sat Sep  5 10:30:15 2026] Code: Bad RIP value.
[Sat Sep  5 10:35:01 2026] cgroup: memory: usage 1000000KB, limit 1000000KB
[Sat Sep  5 10:35:01 2026] Memory cgroup out of memory: Killed process 6789 (java) total-vm:1500000KB, anon-rss:1000000KB, file-rss:0KB, shmem:0KB

Root Cause Analysis

A segmentation fault (SIGSEGV) is a low-level error indicating a serious problem with how a program is managing or accessing memory. In the context of Docker containers, the root causes can be multifaceted:

1. Application-Level Bugs: This is the most frequent cause.

   • Dangling Pointers / Use-After-Free: The application attempts to access memory that has already been deallocated or is no longer valid.
   • Buffer Overflows/Underflows: Writing data beyond the allocated bounds of an array or buffer, corrupting adjacent memory.
   • Null Pointer Dereference: Attempting to read from or write to a memory address pointed to by a null pointer.
   • Stack Overflow: Excessive recursion or large local variables consuming all available stack space.
   • Invalid Type Casts: Incorrectly casting pointers to incompatible types leading to misaligned or unauthorized memory access.
   • Third-party Library Issues: A bug within a library linked by the application.

2. Insufficient Memory / Resource Exhaustion:

   • Docker Memory Limits: The container's configured memory limit (--memory or memory in docker-compose.yml) is too low for the application's runtime needs. When the application tries to allocate more memory than permitted, it can trigger an OOM killer event or a segfault if it attempts to access protected memory after allocation failure.
   • Host System Memory Exhaustion: The Docker host itself is running out of available RAM, leading to the kernel's OOM killer terminating processes (potentially the Docker daemon or critical container processes), or swapped-out memory causing significant performance degradation and potential segfaults when applications try to access data that's no longer quickly available.
   • Swap Space Issues: Lack of sufficient swap space on the host, or a container exceeding its swap limit (--memory-swap).

3. Corrupted Data or Image:

   • Corrupted Container Image: A rare occurrence, but a corrupted Docker image layer or base image could lead to issues during runtime.
   • Corrupted Volume Mounts: If the container uses host-mounted volumes, corrupted filesystems or data on the host volume could lead to the application trying to read invalid data, resulting in a segfault.

4. Hardware Issues:

   • Faulty RAM: Defective RAM modules on the Docker host can cause data corruption in memory, leading to unpredictable segfaults across various applications.

5. Runtime Environment Mismatch:

   • Incorrect Architectures: While Docker prevents running images built for incompatible architectures, subtle issues can arise if libraries are miscompiled or if a specific CPU feature is expected but unavailable.
   • Kernel/ABI Incompatibility: Less common with modern Docker, but specific kernel features or older kernel versions could sometimes interact poorly with certain containerized applications.

Step-by-Step Resolution

Debugging a segmentation fault typically involves a process of elimination, starting from the most common causes.

1. Analyze Docker Logs and Host System dmesg

Start by thoroughly examining all available logs.

• Check Docker Container Logs: The docker logs command is your first line of defense. Look for any stack traces, error messages, or indicators just before the crash. If the application uses a specific language runtime (e.g., JVM, Python interpreter), it might print its own memory error details or a traceback.

  sudo docker logs my-app-container --tail 100
  

• Review Host Kernel Logs (dmesg): The dmesg command shows messages from the kernel buffer. This is crucial for identifying Out-Of-Memory (OOM) killer events or kernel-level reports of segmentation faults.

  sudo dmesg -T | grep -iE 'segfault|oom|memory' | tail -n 20
  

  If you see Memory cgroup out of memory messages, it's a strong indicator that your container hit its Docker memory limit. If you see oom-killer: Kill process ... and your container's process ID is mentioned, it confirms the OOM killer terminated your application.

2. Review and Adjust Docker Resource Limits

If dmesg indicates memory pressure or OOM events, your container likely doesn't have enough memory allocated.

• Inspect Current Container Limits: Use docker inspect to view the currently applied memory limits for your container.

  sudo docker inspect my-app-container | grep -iE 'memory|swap'
  

  Look for Memory and MemorySwap under the HostConfig section.

• Increase Memory and Swap Limits: If the limits are too restrictive, restart your container with increased resources. For docker run:

  sudo docker stop my-app-container
  sudo docker rm my-app-container
  sudo docker run -d --name my-app-container --memory="2g" --memory-swap="4g" my-app-image:latest
  

  For docker-compose.yml:

  version: '3.8'
  services:
    my-app:
      image: my-app-image:latest
      container_name: my-app-container
      deploy:
        resources:
          limits:
            memory: 2G
          reservations:
            memory: 1G # Optional: guarantees this much memory
  

  After modifying docker-compose.yml, run:

  sudo docker-compose up -d --build
  

  When increasing memory limits, ensure your Docker host has enough physical RAM and swap space to accommodate the new limits across all running containers. Over-provisioning can lead to host-level OOM issues. Monitor host memory usage with free -h and vmstat.

3. Test Host System Memory

If multiple containers or applications on the same host are experiencing intermittent segfaults, or if resource limits don't seem to be the issue, suspect faulty RAM on the host.

• Check Host Memory Usage: Monitor overall host memory and swap usage to ensure there's no system-wide pressure.

  free -h
  swapon -s
  

  If swap is heavily utilized or physical memory is consistently low, consider adding more RAM or reducing workload.

• Run Memory Diagnostics: For deeper hardware diagnostics, tools like memtester can be used. This requires stopping critical services or running during a maintenance window.

  # Install memtester
  sudo apt update && sudo apt install -y memtester
  
  # Run memtester (e.g., 2GB of memory for 5 cycles)
  # WARNING: This will consume available memory. Run when host is not under heavy load.
  sudo memtester 2048 5
  

  Any errors reported by memtester indicate faulty RAM.

4. Update and Rebuild Container Image

Sometimes, image corruption during download or subtle issues with base images can cause problems.

• Pull Latest Base Images: Ensure your base images are up-to-date to benefit from bug fixes.

  sudo docker pull ubuntu:20.04 # Or your specific base image
  sudo docker pull alpine:latest # If applicable
  

• Rebuild Your Application Image: Force a rebuild of your application image to ensure all layers are fresh and not corrupted. Use --no-cache to ensure all steps are re-executed.

  sudo docker build --no-cache -t my-app-image:latest .
  sudo docker run -d --name my-app-container my-app-image:latest
  

5. Debug Application Code (If Custom Application)

If the segfault persists and memory limits aren't the issue, the problem is very likely within the application's code. This requires more in-depth debugging.

• Enable Core Dumps in Container: A core dump is a snapshot of the application's memory space at the time of the crash, invaluable for debugging. Docker containers typically disable core dumps by default.

  # Run container with core dumps enabled (ulimit -c unlimited)
  sudo docker run -d --name my-app-debug-container --ulimit core=-1 my-app-image:latest
  
  # Or add to docker-compose.yml
  services:
    my-app:
      image: my-app-image:latest
      ulimits:
        core: -1
  

  When a segfault occurs, a core file will be generated in the container's root filesystem (or a configured path). You'll need to copy it out:

  sudo docker cp my-app-debug-container:/core.<pid> .
  

  You can then analyze the core dump using gdb (GNU Debugger) along with the application binary.

  # Inside a debian/ubuntu container with gdb installed
  # apt update && apt install gdb -y
  gdb /path/to/my_app_binary core.<pid>
  (gdb) bt full # Get full backtrace
  

• Run Application with Debuggers (e.g., gdb) Inside Container: If you can reproduce the issue, run the application directly inside the container with a debugger attached.

  # Start container, but don't run the app yet (override entrypoint)
  sudo docker run -it --entrypoint /bin/bash --name my-app-gdb-container my-app-image:latest
  
  # Inside the container, install gdb (if not present in the image)
  # apt update && apt install gdb -y
  
  # Run your application with gdb
  gdb --args /usr/local/bin/my_app_executable # Replace with your app's actual path and arguments
  (gdb) r # Run the application
  # When it crashes, use:
  (gdb) bt full # Get a full backtrace to pinpoint the code location
  

  This method is more involved and requires source code knowledge, but it's the most direct way to debug application-level segfaults.

6. Check Volume Mounts and Data Integrity

If your container relies on host-mounted volumes for data, ensure these volumes are healthy and accessible.

• Verify Permissions: Ensure the user/group inside the container has appropriate read/write permissions for the mounted directories on the host. Incorrect permissions can lead to access violations.

  ls -la /path/on/host/to/volume
  

• Check Disk Space: A full disk can cause write errors that might lead to unexpected application behavior and segfaults.

  df -h
  

• Inspect Data Integrity: If the application processes critical data from volumes, manually inspect that data for corruption or malformation.

7. Update Docker Engine & Host OS

As a last resort, ensure both your Docker Engine and Ubuntu 20.04 LTS host system are fully updated. Kernel bugs or Docker daemon bugs, though rare, can sometimes contribute to unexpected container behavior.

# Update Docker Engine (if not managed by apt)
# See Docker documentation for official update procedure:
# https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

# Update Host OS
sudo apt update
sudo apt upgrade -y
sudo apt dist-upgrade -y # For significant package changes
sudo reboot # If kernel or critical packages were updated

Always test system and Docker updates in a staging environment before applying them to production systems to prevent unforeseen compatibility issues or regressions.

By systematically working through these steps, from reviewing logs and resource limits to in-depth application debugging, you can effectively diagnose and resolve the "Docker container exited with code 139 segmentation fault" error on your Ubuntu 20.04 LTS systems.