Cómo solucionar el error “OCI runtime create failed” en Docker [Guía actualizada 2026]

スポンサーリンク

Cómo solucionar el error “OCI runtime create failed” en Docker [Guía actualizada 2026]

¿Estás recibiendo el mensaje “Error response from daemon: OCI runtime create failed” al intentar iniciar un contenedor Docker? Este artículo proporciona una guía completa y actualizada para 2026 sobre las causas y soluciones específicas de este error. Ya seas principiante o usuario avanzado, esta guía paso a paso te ayudará a resolver el problema.

¿Qué es este error? Síntomas que experimentarás

El error “OCI runtime create failed” indica que el runtime de contenedores de bajo nivel de Docker, runc, no pudo iniciar el proceso del contenedor. OCI (Open Container Initiative) es una organización industrial que define los estándares de contenedores, y Docker utiliza un runtime compatible con OCI para gestionar los contenedores.

Cuando este error ocurre, tu terminal mostrará mensajes como:

docker: Error response from daemon: OCI runtime create failed:
container_linux.go:380: starting container process caused: exec: "python":
executable file not found in $PATH: unknown.

O:

Error response from daemon: failed to create shim: OCI runtime create failed:
runc create failed: unable to start container process: error during container init:
error mounting "proc" to rootfs at "/proc": permission denied

Cuando este error ocurre, tu contenedor no se iniciará en absoluto. El comando docker run devuelve un error inmediatamente, haciendo imposible acceder a cualquier aplicación dentro del contenedor. Este error puede ocurrir no solo en entornos de desarrollo, sino también en pipelines de CI/CD en producción (CircleCI, GitHub Actions, etc.) y en clústeres de Kubernetes, bloqueando los despliegues por completo.

Lo que hace este error particularmente frustrante es que el mensaje de error es largo y complejo, dificultando la identificación de la causa raíz a primera vista. Sin embargo, la clave está oculta en la parte después de “caused:” en el mensaje de error. Este artículo explica cómo interpretar estas pistas y proporciona soluciones para cada patrón.

Causas de este error

El error “OCI runtime create failed” tiene cinco causas principales. Comprender cada patrón te ayudará a identificar rápidamente el problema a partir del mensaje de error.

Causa 1: Archivo ejecutable no encontrado (executable file not found in $PATH)

Esta es una de las causas más comunes. Ocurre cuando el ejecutable especificado en ENTRYPOINT o CMD del Dockerfile no existe en el $PATH de la imagen del contenedor. Los casos específicos incluyen:

  • Errores tipográficos en el nombre del comando (por ejemplo, escribir pytohn en lugar de python)
  • La imagen base no incluye el comando requerido (por ejemplo, bash no está incluido en imágenes alpine)
  • Olvidar copiar binarios a la imagen final en construcciones de múltiples etapas
  • Configuración incorrecta de WORKDIR que impide la resolución de rutas de scripts

Causa 2: Problemas de permisos (permission denied)

Ocurre cuando el proceso de inicio del contenedor carece de los permisos necesarios para acceder a archivos o directorios. Los casos comunes incluyen:

  • El script de punto de entrada no tiene permisos de ejecución (chmod +x)
  • SELinux o AppArmor en la máquina host está bloqueando el acceso a archivos del contenedor
  • Etiquetado inadecuado de volúmenes montados por enlace
  • Propiedad de archivos corrupta bajo /var/lib/docker

Causa 3: Versiones obsoletas de Docker o runc

Las versiones antiguas de Docker Engine, containerd o runc pueden causar problemas de compatibilidad con las funciones más recientes del kernel. En particular, las versiones de Docker inferiores a 25 han sido reportadas como problemáticas en distribuciones Linux recientes. La compatibilidad también puede romperse después de actualizaciones del sistema operativo host (por ejemplo, Proxmox VE 8.1 a 8.2).

Causa 4: Problemas de compatibilidad con cgroup v2

Las distribuciones Linux recientes (Ubuntu 22.04+, Fedora 31+, etc.) tienen cgroup v2 habilitado por defecto. Las versiones antiguas de Docker o runc que no soportan cgroup v2 producirán errores como:

OCI runtime create failed: runc create failed: unable to start container process:
error during container init: error setting cgroup config for procHooks process

cgroup v2 requiere kernel 4.15 o superior (se recomienda 5.2+).

Causa 5: Agotamiento de espacio en disco y conflictos de recursos

Cuando las imágenes y contenedores de Docker agotan el espacio disponible en disco, este error aparece con un mensaje no space left on device. Los conflictos con puertos o directorios ya en uso también pueden causar este error.

Solución 1: Interpretar mensajes de error y corregir problemas con ejecutables (Recomendado)

El enfoque más importante y efectivo es interpretar correctamente el mensaje de error. Para este error, la razón específica del fallo se indica después de caused:.

Paso 1: Analizar el mensaje de error

Primero, examina cuidadosamente el mensaje de error. Aquí está la estructura típica:

Error response from daemon: OCI runtime create failed:
container_linux.go:380: starting container process caused:
exec: "python": executable file not found in $PATH: unknown

En este caso, después de caused:, dice exec: "python": executable file not found in $PATH. Esto significa que el comando “python” no fue encontrado en el PATH del contenedor.

Paso 2: Verificar y corregir el Dockerfile

Si el error está relacionado con archivos ejecutables, verifica tu Dockerfile:

# Ejemplo incorrecto: la imagen alpine no incluye python
FROM alpine:latest
CMD ["python", "app.py"]

# Ejemplo correcto: usar la imagen oficial de Python
FROM python:3.12-slim
COPY app.py /app/
WORKDIR /app
CMD ["python", "app.py"]

Para errores de bash no encontrado (comunes con imágenes basadas en Alpine Linux):

# Ejemplo incorrecto
RUN /bin/bash -c "echo hello"

# Ejemplo correcto: Alpine incluye ash por defecto
RUN /bin/sh -c "echo hello"

# O instalar bash
RUN apk add --no-cache bash

Paso 3: Verificar archivos dentro del contenedor

Puedes iniciar la imagen de forma interactiva para verificar la existencia de archivos:

# Entrar al contenedor con un shell especificado
docker run --rm -it --entrypoint /bin/sh myimage:latest

# Verificar comandos en PATH
which python
echo $PATH
ls -la /app/

Notas importantes

  • Si usas construcciones de múltiples etapas, verifica que todos los binarios necesarios se copien a la etapa final
  • Si tanto ENTRYPOINT como CMD están configurados, verifica cómo se combinan (forma exec vs forma shell)
  • Verifica que las instrucciones COPY copien correctamente los archivos y que .dockerignore no los excluya

Solución 2: Corregir permisos y políticas de seguridad

Si el mensaje de error contiene “permission denied”, el problema está relacionado con permisos o políticas de seguridad.

Otorgar permisos de ejecución al script de punto de entrada

# Otorgar permisos de ejecución localmente
chmod +x entrypoint.sh

# Otorgar permisos en el Dockerfile
COPY entrypoint.sh /app/
RUN chmod +x /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

Manejo en entornos SELinux

En entornos con SELinux habilitado (RHEL, CentOS, Fedora, etc.), las políticas pueden bloquear el acceso del contenedor a archivos del host.

# Verificar el estado de SELinux
sestatus

# Verificar los registros de denegación de SELinux
sudo ausearch -m avc -ts recent

# Método 1: Agregar sufijo :z o :Z al montar volúmenes (recomendado)
docker run -v /host/data:/container/data:z myapp:latest

# Método 2: Deshabilitar etiquetas SELinux para depuración (no recomendado en producción)
docker run --security-opt label=disable myapp:latest

El sufijo :z hace que el volumen sea compartible entre múltiples contenedores, mientras que :Z lo etiqueta exclusivamente para ese contenedor. Siempre usa :z o :Z en producción y evita label=disable.

Manejo en entornos AppArmor

Problemas similares pueden ocurrir con AppArmor en Ubuntu y otros sistemas. Notablemente, desde el parche de seguridad de containerd.io 1.7.28-2 en noviembre de 2025, los errores relacionados con AppArmor han aumentado al ejecutar Docker dentro de contenedores LXC anidados.

# Deshabilitar perfil AppArmor para depuración (no recomendado en producción)
docker run --security-opt apparmor=unconfined myapp:latest

# Verificar el estado de AppArmor
sudo aa-status

Corregir propiedad de archivos

# Verificar propiedad de /var/lib/docker
ls -la /var/lib/docker/

# Reiniciar el daemon de Docker si es necesario
sudo systemctl restart docker

Solución 3: Actualizar Docker/runc y corregir la configuración de cgroup (Avanzado)

Los problemas de compatibilidad de versiones y configuración del kernel requieren soluciones más profundas.

Actualizar Docker Engine

Actualizar a Docker 25 o superior resuelve muchos problemas de compatibilidad.

# Verificar la versión actual de Docker
docker version

# Para Ubuntu/Debian: actualizar desde el repositorio oficial de Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Para CentOS/RHEL
sudo yum update docker-ce docker-ce-cli containerd.io

Actualizar runc por separado

También puedes actualizar runc de forma independiente:

# Verificar la versión de runc
runc --version

# Instalar la última versión de runc desde GitHub
wget https://github.com/opencontainers/runc/releases/download/v1.2.5/runc.amd64
sudo install -m 755 runc.amd64 /usr/local/sbin/runc

Resolver compatibilidad con cgroup v2

Si estás experimentando errores relacionados con cgroup v2:

# Verificar la versión actual de cgroup
stat -fc %T /sys/fs/cgroup/
# "cgroup2fs" significa que v2 está habilitado

# Verificar la versión del kernel (se recomienda 5.2+)
uname -r

Método A: Modificar la configuración del daemon de Docker

# Editar /etc/docker/daemon.json
sudo tee /etc/docker/daemon.json <<EOF
{
  "default-cgroupns-mode": "host",
  "exec-opts": ["native.cgroupdriver=systemd"]
}
EOF

# Reiniciar Docker
sudo systemctl daemon-reload
sudo systemctl restart docker

Método B: Volver a cgroup v1 (no recomendado pero efectivo en emergencias)

Agrega lo siguiente a los parámetros de arranque de GRUB para forzar cgroup v1:

# Editar /etc/default/grub
GRUB_CMDLINE_LINUX="systemd.unified_cgroup_hierarchy=0"

# Actualizar GRUB y reiniciar
sudo update-grub
sudo reboot

Verificar y liberar espacio en disco

# Verificar el espacio en disco usado por Docker
docker system df

# Eliminar todas las imágenes, contenedores y volúmenes no utilizados
docker system prune -a --volumes

# Eliminar imágenes colgantes
docker image prune

Verificar la configuración del servicio systemd

En algunos entornos, la configuración del archivo de unidad systemd de Docker puede causar problemas:

# Verificar el archivo de unidad del servicio Docker
sudo systemctl cat docker.service

# Si MountFlags=slave está configurado, eliminarlo
sudo systemctl edit docker.service
# [Service]
# MountFlags=

# Aplicar cambios
sudo systemctl daemon-reload
sudo systemctl restart docker

Cómo prevenir este error

Sigue estas mejores prácticas para prevenir el error “OCI runtime create failed”.

1. Seguir las mejores prácticas de Dockerfile

  • Usar imágenes oficiales como base
  • En construcciones de múltiples etapas, verificar que la etapa final contenga todos los archivos necesarios
  • Comprender y usar correctamente la diferencia entre ENTRYPOINT y CMD
  • Configurar adecuadamente el archivo .dockerignore

2. Probar exhaustivamente en local

# Probar que la imagen construida se inicia correctamente
docker build -t myapp:test .
docker run --rm myapp:test

3. Mantener actualizado el entorno Docker

Actualiza regularmente Docker Engine, containerd y runc. Aplica rápidamente las actualizaciones menores que contengan parches de seguridad.

4. Monitorear el espacio en disco regularmente

# Verificar periódicamente el uso del disco
docker system df
# Limpieza regular de recursos no utilizados
docker system prune -f --filter "until=168h"

5. Fijar versiones de Docker en pipelines CI/CD

Al usar Docker en CI/CD, fija la versión de Docker para prevenir problemas de compatibilidad inesperados.

Resumen

El error “OCI runtime create failed” de Docker puede parecer complejo, pero al leer cuidadosamente la parte después de caused: en el mensaje de error, identificar la causa raíz es relativamente sencillo.

Puntos clave:

  1. Ejecutable no encontrado → Verifica ENTRYPOINT/CMD en tu Dockerfile y especifica la ruta y comando correctos
  2. Errores de permisos → Verifica los permisos de ejecución del script y la configuración de SELinux/AppArmor
  3. Problemas de compatibilidad de versiones → Actualiza Docker, runc y el kernel a la última versión
  4. Problemas relacionados con cgroup → Ajusta la configuración de cgroup en daemon.json
  5. Problemas de espacio en disco → Limpia recursos innecesarios con docker system prune

Si los métodos de este artículo no resuelven tu problema, intenta:

  • Publicar una pregunta en Docker Community Forums (forums.docker.com)
  • Buscar issues en el repositorio de GitHub moby/moby
  • Preguntar en Stack Overflow con la salida de docker info y docker version

Copiar el mensaje de error completo y buscarlo es el primer paso más eficiente hacia la resolución.

Referencias

コメント

タイトルとURLをコピーしました