Docker «OCI runtime create failed»: descifra el error y arregla la causa real

noviembre 24, 2025 • febrero 3, 2026 • Lectura: 24 min • Views: 11

¿Te fue útil?

Escribes docker run. Docker piensa medio segundo. Luego falla con:
OCI runtime create failed y una pared de texto vagamente acusatoria. Nada arranca. Suena la alarma.
La causa raíz normalmente no es “OCI”. Casi siempre es una falla muy específica del kernel, sistema de archivos, seguridad o configuración
que Docker está informando—de forma deficiente.

Esta es una guía de campo para producción: cómo leer el error como si fuera una traza de pila, localizar la capa que falla y arreglar el
problema real sin reinicios rituales. Iremos desde “¿qué hace OCI aquí?” hasta comandos concretos,
salidas esperadas y decisiones que deberías tomar.

Decodificar el error: qué significa realmente “OCI runtime create failed”

El titular es engañoso. “OCI runtime create failed” no es un error singular. Es un cajón de sastre. Docker te está diciendo:
“Le pedí al runtime OCI que crease un contenedor, y algo en la fase de preparación del runtime explotó”.

Esa “fase de preparación” incluye:

crear namespaces (pid, mount, network, user)
configurar cgroups
preparar el sistema de ficheros raíz (montajes overlay, bind mounts, tmpfs)
aplicar políticas de seguridad (seccomp, AppArmor/SELinux)
configurar el proceso init y ejecutar tu entrypoint

Cuando cualquiera de esos pasos falla, Docker frecuentemente imprime un mensaje que comienza con:
docker: Error response from daemon: OCI runtime create failed: ...
y luego una cadena anidada como container_linux.go, process_linux.go,
failed to create shim task, permission denied, invalid argument, o no space left on device.

Tu trabajo es ignorar el prefijo genérico y obsesionarte con la última queja específica de estilo syscall.
Esa última parte suele ser la verdad.

Una regla seca: trata este error como un error del kernel con el abrigo de Docker puesto. Arregla el problema que enfrenta el kernel, no el abrigo.

Broma #1 (corta, relevante): los errores OCI son como la luz de “check engine”: avisan que algo está mal, pero no ayudan sobre qué cilindro está en llamas.

Datos e historia: por qué existe este error

Un poco de contexto ayuda porque los errores OCI están moldeados por cómo evolucionaron los contenedores: capas de estándares, runtimes y daemons
que se comunican por APIs. Aquí hay hechos concretos que explican la rareza.

Los contenedores Linux existían antes que Docker. cgroups llegaron a Linux alrededor de 2007–2008; los namespaces maduraron en los 2000s. Docker popularizó el empaquetado.
Docker usó LXC por defecto originalmente. Las primeras versiones usaban LXC; luego pasó a libcontainer (Go) y finalmente se estandarizó en runc.
OCI (Open Container Initiative) se creó en 2015. El objetivo: especificaciones de imagen y runtime para que “contenedor” signifique algo portable.
runc proviene de libcontainer de Docker. runc es el runtime de referencia OCI; muchos runtimes implementan la misma especificación.
containerd se separó para reducir el acoplamiento. Docker delegó más en containerd; verás errores que mencionan “shim” porque containerd usa shims para gestionar procesos de contenedores.
El paso “create” de OCI no es “arrancar tu app”. “Create” significa configurar el estado y el entorno del contenedor; el exec de la app es tardío y falla por razones totalmente distintas.
cgroup v2 cambió valores por defecto y suposiciones. Las distribuciones cambiaron la jerarquía por defecto; algunas configuraciones de Docker rompieron hasta que se ajustaron para cgroups systemd y drivers compatibles.
Los módulos de seguridad cambiaron su comportamiento con el tiempo. La evolución de políticas SELinux y AppArmor puede convertir un contenedor que funcionaba en un fallo repentino de “permission denied”.
OverlayFS tiene flags de características del kernel. Ciertos modos de overlay (como metacopy, redirect_dir, montajes idmapped) dependen de versiones del kernel y pueden fallar de forma extraña cuando se activan/desactivan.

Guía rápida de diagnóstico (hacer en este orden)

Cuando la producción está en llamas necesitas un algoritmo de camino más corto, no una clase de filosofía. Este es el orden que suele
encontrar el cuello de botella rápidamente.

1) Captura la cadena completa del error

Vuelve a ejecutar el comando con máximo contexto del daemon (logs + events).
Extrae la falla final: permission denied, no space left on device, invalid argument, exec format error, operation not permitted.

2) Comprueba las “mentiras obvias” a nivel host: disco, inodos, memoria, logs del kernel

Disco/inodos en la raíz de Docker (/var/lib/docker o ruta personalizada).
dmesg/journal por denegaciones AppArmor/SELinux o fallos de montaje.
Memoria/presión de cgroup si la cadena de errores insinúa fallos de fork/exec.

3) Identifica el subsistema que falla según el último error

Mount/rootfs: errores de mount overlay2, “unknown filesystem”, “invalid argument”, “permission denied”.
Seguridad: denegaciones AppArmor/SELinux AVC; seccomp “operation not permitted”.
cgroups: errores que mencionan rutas de cgroup, controladores o systemd.
Entrypoint: “exec format error”, “no such file or directory” (a menudo falta el intérprete), “text file busy”.

4) Reproduce con el contenedor más pequeño posible

Prueba una imagen conocida buena y un comando trivial (como busybox true).
Si incluso eso falla, es el host/runtime. Si solo una imagen falla, es configuración de imagen, entrypoint o mounts.

5) Arregla una cosa y vuelve a probar

No hagas una secuencia de “reinicia Docker, reinicia nodo, desactiva seguridad”. Haz un cambio, valida, sigue.
Estás depurando, no ejecutando un ritual.

Mapear la falla por capas: Docker → containerd → runc → kernel

Si quieres ser rápido, piensa por capas y busca el log correcto.

Docker CLI imprime el error resumido. Útil para la cadena final, no para los detalles.
dockerd logs muestran qué pidió Docker a containerd y qué regresó.
containerd logs muestran llamadas al shim y runtime. “failed to create shim task” suele aparecer aquí.
runc hace las llamadas al kernel. Sus errores son los que más importan.
kernel logs (dmesg/journal) a menudo contienen la denegación real o el rechazo de montaje, especialmente para LSMs.

“OCI runtime create failed” suele significar que runc devolvió no cero durante create.
El paso create incluye montar tu rootfs y los bind mounts. Así que almacenamiento y seguridad dominan los fallos.

Cita (idea parafraseada): La idea parafraseada de Werner Vogels: todo falla, todo el tiempo—tu trabajo es construir sistemas que lo esperen y lo manejen.

Tareas prácticas: 12+ comandos con salidas y decisiones

A continuación hay tareas prácticas que puedes ejecutar en un host Linux con Docker Engine. Cada una incluye:
el comando, qué significa una salida típica y la decisión a tomar. Ejecútalas en el orden que coincida con tus síntomas,
no necesariamente de arriba abajo.

Task 1: Reejecuta el contenedor fallido con máxima claridad

cr0x@server:~$ docker run --rm --name oci-test alpine:3.20 true
docker: Error response from daemon: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open /proc/self/fd: permission denied: unknown.

Qué significa: La última cláusula (open /proc/self/fd: permission denied) es tu pista. Apunta a políticas de seguridad (SELinux/AppArmor/seccomp) o a un comportamiento reforzado del montaje de /proc.

Decisión: Ve a logs del kernel/LSM (Tareas 4–6) antes de tocar almacenamiento.

Task 2: Verifica si el problema es global o específico de la imagen

cr0x@server:~$ docker run --rm busybox:1.36 true
Unable to find image 'busybox:1.36' locally
1.36: Pulling from library/busybox
Digest: sha256:...
Status: Downloaded newer image for busybox:1.36
docker: Error response from daemon: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open /proc/self/fd: permission denied: unknown.

Qué significa: Si incluso BusyBox falla, tu entorno del host/runtime está roto, no tu imagen de aplicación.

Decisión: Enfócate en la configuración del daemon, características del kernel, políticas LSM, cgroups y salud del driver de almacenamiento.

Task 3: Lee los logs del daemon Docker alrededor del fallo

cr0x@server:~$ sudo journalctl -u docker --since "10 min ago" --no-pager
Jan 03 09:41:18 server dockerd[1327]: time="2026-01-03T09:41:18.912345678Z" level=error msg="Handler for POST /v1.45/containers/create returned error: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open /proc/self/fd: permission denied: unknown"
Jan 03 09:41:18 server dockerd[1327]: time="2026-01-03T09:41:18.913456789Z" level=info msg="Attempting next endpoint for containerd"

Qué significa: dockerd está repitiendo el error del runtime, pero confirma la línea de tiempo y que no es un fallo del cliente.

Decisión: Si los logs de dockerd muestran “permission denied”, “invalid argument”, “no space”, etc., sigue esa frase exacta hacia abajo.

Task 4: Lee los logs de containerd (donde aparecen shim/runc)

cr0x@server:~$ sudo journalctl -u containerd --since "10 min ago" --no-pager
Jan 03 09:41:18 server containerd[1189]: time="2026-01-03T09:41:18.905432198Z" level=error msg="RunPodSandbox for "..." failed" error="failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open /proc/self/fd: permission denied: unknown"

Qué significa: “failed to create shim task” es la forma de containerd de decir que el runtime no pudo configurar el contenedor. La última cláusula sigue siendo la clave.

Decisión: Si ves errores relacionados con mounts aquí, ve a las comprobaciones de almacenamiento. Si ves permission/denied, ve a comprobaciones LSM.

Task 5: Comprueba logs del kernel por denegaciones AppArmor

cr0x@server:~$ sudo dmesg -T | tail -n 20
[Fri Jan  3 09:41:18 2026] audit: type=1400 audit(1735897278.912:312): apparmor="DENIED" operation="open" profile="docker-default" name="/proc/self/fd/" pid=24310 comm="runc:[2:INIT]" requested_mask="r" denied_mask="r" fsuid=0 ouid=0

Qué significa: Es una pista clara. AppArmor bloqueó al proceso init de runc de leer /proc/self/fd.

Decisión: Arregla el perfil de AppArmor o ejecuta contenedores con una anulación de perfil apropiada (ver Errores comunes y checklist). No desactives AppArmor globalmente a menos que te guste vivir peligrosamente.

Task 6: Comprueba denegaciones SELinux (RHEL/Fedora/CentOS y derivados)

cr0x@server:~$ sudo ausearch -m avc -ts recent | tail -n 5
type=AVC msg=audit(1735897278.912:312): avc:  denied  { mounton } for  pid=24310 comm="runc:[2:INIT]" path="/var/lib/docker/overlay2/..." scontext=system_u:system_r:container_runtime_t:s0 tcontext=system_u:object_r:default_t:s0 tclass=dir permissive=0

Qué significa: SELinux bloqueó una operación de montaje. Que el tcontext sea default_t es sospechoso; las etiquetas están mal o la ruta de almacenamiento no está etiquetada para contenedores.

Decisión: Restaura contextos correctos en las rutas de almacenamiento de Docker, o ajusta la política correctamente. Evita poner SELinux en permissive como “solución”; es, como mucho, un paso diagnóstico.

Task 7: Comprueba el driver de almacenamiento y directorio raíz de Docker

cr0x@server:~$ docker info --format 'Driver={{.Driver}} RootDir={{.DockerRootDir}} CgroupDriver={{.CgroupDriver}}'
Driver=overlay2 RootDir=/var/lib/docker CgroupDriver=systemd

Qué significa: Ahora sabes dónde están los datos y qué driver está involucrado. overlay2 es lo normal; también implica que los mounts y el soporte de overlay en el kernel importan.

Decisión: Si RootDir está sobre un filesystem extraño (NFS, eCryptfs, XFS antiguo sin ftype), espera problemas. Valida el sistema de ficheros de respaldo a continuación.

Task 8: Comprueba espacio en disco e inodos en el filesystem de Docker RootDir

cr0x@server:~$ df -h /var/lib/docker
Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme0n1p3  200G  198G  2.0G  99% /

cr0x@server:~$ df -i /var/lib/docker
Filesystem       Inodes   IUsed    IFree IUse% Mounted on
/dev/nvme0n1p3  13107200 13090000  17200   100% /

Qué significa: “No space left on device” puede ser por bloques de disco o por inodos. Overlay2 consume muchos inodos.

Decisión: Si cualquiera está casi lleno, deja de depurar cosas elegantes. Libera espacio (Task 9) o amplía el almacenamiento. Los contenedores no pueden montar capas si el filesystem no puede crear metadatos.

Task 9: Recuperar espacio de Docker con seguridad (y entender lo que borras)

cr0x@server:~$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          54        12        38.6GB    22.4GB (58%)
Containers      17        2         1.1GB     1.0GB (91%)
Local Volumes   31        10        96.2GB    40.5GB (42%)
Build Cache     0         0         0B        0B

cr0x@server:~$ docker system prune -f
Deleted Containers:
...
Deleted Images:
...
Total reclaimed space: 12.3GB

Qué significa: docker system df muestra dónde está el espacio. Prune elimina contenedores detenidos, imágenes colgantes y redes no usadas. Los volúmenes solo se eliminan con --volumes.

Decisión: En producción, prune es aceptable si entiendes tu estrategia de caché de imágenes y no dependes de contenedores detenidos como evidencia forense. Para nodos que se reconstruyen a menudo, prune proactivamente con salvaguardas.

Task 10: Valida el filesystem de respaldo para overlay2 (XFS ftype)

cr0x@server:~$ findmnt -no FSTYPE,OPTIONS /var/lib/docker
xfs rw,relatime,attr2,inode64,logbufs=8,logbsize=32k,noquota

cr0x@server:~$ sudo xfs_info /dev/nvme0n1p3 | grep ftype
naming   =version 2              bsize=4096   ascii-ci=0, ftype=1

Qué significa: Overlay2 sobre XFS necesita ftype=1. Si es ftype=0, acabarás con comportamientos extraños de overlay y fallos al iniciar contenedores.

Decisión: Si ftype=0, la solución correcta es migrar Docker RootDir a un filesystem formateado correctamente. No hay una conversión segura in-place.

Task 11: Comprueba la propagación de montajes / shared mounts (común en hosts Kubernetes también)

cr0x@server:~$ findmnt -o TARGET,PROPAGATION /var/lib/docker
TARGET          PROPAGATION
/var/lib/docker shared

Qué significa: Algunas cargas requieren propagación de montaje shared; otras fallan si el layout de montajes del host es inusual. Si está private en un entorno que espera shared, puedes ver fallos de create relacionados con mounts.

Decisión: Si sospechas problemas de propagación de montajes, compara con un nodo conocido bueno y alinea las unidades de systemd mount. Evita un mount --make-rshared / aleatorio en producción a menos que entiendas el radio de impacto.

Task 12: Inspecciona el estado de seccomp y prueba con un perfil no confinado (solo diagnóstico)

cr0x@server:~$ docker info --format 'SecurityOptions={{json .SecurityOptions}}'
SecurityOptions=["name=seccomp,profile=default","name=apparmor"]

cr0x@server:~$ docker run --rm --security-opt seccomp=unconfined alpine:3.20 true
docker: Error response from daemon: OCI runtime create failed: runc create failed: unable to start container process: error during container init: open /proc/self/fd: permission denied: unknown.

Qué significa: Seccomp no confinado no cambió nada. Eso sugiere que seccomp no es la causa (en este ejemplo); probablemente es AppArmor.

Decisión: Usa las anulaciones no confinadas como experimentos controlados. Si unsetting lo “arregla”, entonces crea un perfil correcto en lugar de dejarlo abierto.

Task 13: Valida el modo y jerarquía de cgroup (común con cgroup v2)

cr0x@server:~$ stat -fc %T /sys/fs/cgroup
cgroup2fs

cr0x@server:~$ docker info --format 'CgroupVersion={{.CgroupVersion}} CgroupDriver={{.CgroupDriver}}'
CgroupVersion=2 CgroupDriver=systemd

Qué significa: Estás en cgroup v2 y Docker usa el driver systemd (generalmente correcto para distros modernas). Si ves una descoordinación (cgroup v2 con driver cgroupfs en algunas configuraciones), puedes obtener fallos de create.

Decisión: Alinea el driver de cgroup de Docker con systemd en hosts systemd. Si estás en un rincón legacy, prueba en un nodo conocido bueno antes de cambiar a toda la flota.

Task 14: Confirma que el binario del entrypoint es ejecutable y coincide con la arquitectura

cr0x@server:~$ docker run --rm --entrypoint /bin/sh alpine:3.20 -c 'uname -m; file /bin/busybox'
x86_64
/bin/busybox: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-musl-x86_64.so.1, stripped

Qué significa: Si tu imagen fallida tiene un binario ARM en un host x86_64, verás exec format error durante create/start. Esta comprobación demuestra cómo se ve “normal”.

Decisión: Si hay desajuste de arquitectura, corrige la construcción de la imagen o usa manifests multi-arch correctamente. No “arregles” instalando emulación qemu en nodos prod salvo que sea absolutamente necesario y entiendas las implicaciones de rendimiento.

Task 15: Valida que los bind mounts existen y tienen permisos correctos

cr0x@server:~$ docker run --rm -v /does-not-exist:/data alpine:3.20 true
docker: Error response from daemon: OCI runtime create failed: runc create failed: unable to start container process: error during container init: error mounting "/does-not-exist" to rootfs at "/data": mount /does-not-exist:/data, flags: 0x5000: no such file or directory: unknown.

Qué significa: Una ruta host ausente causa una falla OCI create porque la configuración de mounts ocurre antes de que el proceso empiece.

Decisión: Arregla la ruta host, créala con la propiedad correcta, o usa volúmenes gestionados por Docker en lugar de rutas host frágiles.

Task 16: Detecta explícitamente errores de montaje overlay2

cr0x@server:~$ sudo grep -R "overlay" -n /var/log/syslog | tail -n 5
Jan 03 09:41:18 server kernel: [Fri Jan  3 09:41:18 2026] overlayfs: upper fs does not support tmpfile.
Jan 03 09:41:18 server kernel: [Fri Jan  3 09:41:18 2026] overlayfs: failed to mount overlay: invalid argument

Qué significa: El filesystem de respaldo carece de características que overlay espera. Esto puede venir de filesystems exóticos, ciertas opciones de montaje o kernels antiguos.

Decisión: Mueve Docker RootDir a un FS local soportado (ext4 o XFS configurado correctamente), o actualiza kernel/configuración de almacenamiento para cumplir los requisitos de overlay.

Broma #2 (corta, relevante): Desactivar SELinux para “arreglar Docker” es como quitar tu detector de humo porque hace mucho ruido.

Tres mini-historias corporativas desde el frente

Mini-historia 1: El incidente causado por una suposición equivocada

Una empresa mediana corría Docker en una flota de VMs de propósito general. Un equipo gestionaba “la imagen base”, otro el “plataforma”.
El equipo de plataforma desplegó un cambio de hardening: nuevas políticas AppArmor y una actualización del kernel. La suposición era simple y equivocada:
“Los contenedores están aislados; un perfil de host más estricto no los afectará.”

Lunes por la mañana, un subconjunto de servicios dejó de desplegar. El síntoma fue idéntico en todos lados:
OCI runtime create failed con open /proc/self/fd: permission denied.
Los equipos inicialmente culparon la imagen porque el fallo aparecía al iniciar contenedores. Algunos ingenieros perdieron horas reconstruyendo imágenes
y rotando tags, porque por supuesto debía ser “la app”.

El avance vino de alguien que leyó dmesg en lugar de Slack.
Los logs de auditoría del kernel mostraron denegaciones de AppArmor contra docker-default.
La actualización de política restringió el acceso a rutas /proc de formas que al proceso init de runc no le gustaron.
Docker no estaba roto. La postura de seguridad del host sí, en relación con su runtime.

La solución fue quirúrgica: ajustar el perfil de AppArmor usado por esas cargas y desplegarlo a la flota con canary.
También escribieron un runbook de una página: “Si el error termina con permission denied, revisa logs LSM primero.”
El incidente podría haber durado 20 minutos. Duró casi medio día por la suposición inicial equivocada.

Mini-historia 2: La optimización que salió mal

Otra organización intentó optimizar velocidad de build y deploy en runners CI. Pusieron Docker RootDir en un filesystem de red
porque era “almacenamiento rápido” y facilitaba limpieza. Además evitaba actualizar discos locales. A todos les gusta un proyecto que
aparenta ahorrar dinero moviendo la complejidad a otro sitio.

Funcionó un tiempo. Luego trabajos aleatorios empezaron a fallar con OCI runtime create failed,
usualmente descrito como fallos de montaje o “invalid argument”. Era intermitente. Eso fue lo peor.
Las fallas intermitentes consumen tiempo de ingeniería en silencio.

El problema real: overlay2 sobre un filesystem no local es un campo minado de compatibilidad. Aunque “funcione”, puedes encontrar casos límite:
semánticas de bloqueo de archivos, soporte d_type, soporte tmpfile, picos de latencia durante mounts y carreras sensibles al tiempo
cuando miles de capas churnean a diario.

El rollback fue poco glamuroso: mover Docker RootDir de vuelta a SSD local, aplicar cuotas de pruning y aceptar que la caché de build es
una característica de rendimiento, no una estrategia de retención de datos. Dejaron de ver fallos de create inmediatamente. El diseño “optimizado”
estaba optimizando lo equivocado: conveniencia de almacenamiento, no corrección del runtime.

Mini-historia 3: La práctica aburrida pero correcta que salvó el día

Una gran empresa corría una flota mixta: diferentes kernels, distros y regímenes de cumplimiento.
Eran alérgicos a las interrupciones, así que hicieron algo poco fashion: estandarizaron la base de los hosts de contenedores.
Mismo tipo y opciones de filesystem para Docker RootDir, mismo driver de cgroup, misma configuración de módulos de seguridad,
y un conjunto estrecho de versiones de kernel probadas.

Un día un nuevo servicio empezó a fallar en un único cluster con OCI runtime create failed y invalid argument.
El ingeniero on-call comparó el nodo con su baseline conocido bueno usando una pequeña checklist:
docker info, tipo de filesystem, versión de kernel y un escaneo rápido de logs del kernel.

El culpable apareció rápido: un subconjunto de nodos se aprovisionó con un volumen XFS antiguo donde ftype=0
debido a un script de imagen obsoleto. No rompió todo inmediatamente; rompió lo suficientemente para ser molesto y solo bajo ciertos patrones de capas.

Como tenían un baseline, la solución no fue un debate. Drenaron esos nodos, los reconstruyeron con ajustes correctos del filesystem
y devolvieron la capacidad. Sin heroísmos, sin “desactivar seguridad”, sin flags experimentales de madrugada. Lo aburrido ganó, otra vez.

Errores comunes: síntomas → causa raíz → reparación

Las fallas de OCI create parecen repetitivas, pero las causas raíz no lo son. Aquí están los patrones que más aparecen en producción,
mapeados como realmente los depuras.

1) “permission denied” durante init del contenedor

Síntoma: El error termina con permission denied, a menudo mencionando /proc, mounts o ficheros bajo /var/lib/docker.

Causa raíz: Denegación por AppArmor/SELinux, etiquetas incorrectas en directorios Docker, o opciones de montaje restrictivas.

Reparación: Revisa dmesg y logs de auditoría. Restaura contextos SELinux en Docker RootDir; ajusta el perfil AppArmor. Usa --security-opt solo como diagnóstico, luego implementa una política adecuada.

2) “no space left on device” pero tienes GBs libres

Síntoma: OCI create falla con ENOSPC mientras df -h muestra espacio.

Causa raíz: Inodos agotados (df -i) o Docker RootDir está en un filesystem más pequeño de lo que crees (bind-mounted en otro sitio).

Reparación: Comprueba df -i y docker info RootDir. Prune capas no usadas; expande el filesystem; considera mover RootDir a un volumen dedicado.

3) “invalid argument” alrededor de montajes overlay

Síntoma: failed to mount overlay: invalid argument o similar en logs del kernel.

Causa raíz: Filesystem de respaldo no soportado (NFS, XFS con configuración antigua, opciones de montaje incompatibles) o desajuste de características kernel/overlay.

Reparación: Coloca Docker RootDir en FS local soportado; verifica XFS ftype=1; actualiza kernel si hace falta; deja de intentar usar overlay2 en almacenamientos “creativos”.

4) “exec format error” o “no such file or directory” al iniciar

Síntoma: El contenedor falla inmediatamente; la cadena de error termina con fallos de exec.

Causa raíz: Binario de arquitectura equivocada; intérprete faltante (p. ej. script con #!/bin/bash pero sin bash); finales de línea CRLF en scripts de entrypoint que confunden.

Reparación: Verifica arquitectura de la imagen y entrypoint. Asegura que los intérpretes existan. Construye imágenes multi-arch correctamente.

5) Fallos de bind mount

Síntoma: Error menciona “error mounting” ruta host, “no such file” o “not a directory”.

Causa raíz: Ruta host ausente, tipo incorrecto (archivo vs directorio), o permisos/etiquetas que impiden el montaje.

Reparación: Crea la ruta, corrige permisos y contextos SELinux, o cambia a volúmenes nombrados.

6) Errores de cgroup (especialmente tras actualizaciones del SO)

Síntoma: OCI create falla mencionando cgroups, controladores o systemd.

Causa raíz: Problemas de transición a cgroup v2, driver de cgroup de Docker desalineado o controladores bloqueados.

Reparación: Alinea al driver systemd en hosts systemd; asegúrate de que los controladores necesarios estén habilitados; valida con docker info y stat -fc %T /sys/fs/cgroup.

Listas de verificación / plan paso a paso

Checklist de incidente: restaura el servicio primero, luego repara bien

Obtén la cadena final exacta del error.
Reejecuta un contenedor mínimo y captura la salida.
Decide si huele a almacenamiento, seguridad, cgroups o entrypoint.
Confirma que no es específico de la imagen.
Ejecuta busybox true.
Si eso falla, deja de culpar a la app.
Comprueba capacidad del host (bloques + inodos) en Docker RootDir.
Si está lleno, prune o expande. No lo complique.
Revisa logs del kernel por denegaciones y errores de montaje.
Si ves denegaciones AppArmor/SELinux, ya tienes la categoría de la causa raíz.
Compara un nodo roto con uno bueno.
¿Mismo kernel? ¿mismo filesystem? ¿misma config de Docker? ¿mismas opciones de seguridad?
Las diferencias suelen ser la respuesta.
Aplica la mitigación más pequeña y segura.
Ejemplos: liberar espacio, restaurar etiquetas, ajustar un perfil, arreglar una ruta de montaje.
Evita “desactivar todo el módulo de seguridad” salvo que sea un diagnóstico corto con plan de reversión.
Vuelve a probar con un contenedor mínimo, luego con la carga real.
Si el mínimo funciona pero la app no, pasaste de debugging a nivel host a debugging a nivel app (entrypoint, mounts, permisos de usuario).

Checklist de prevención: evita que el tú del futuro se encuentre con el tú del presente

Coloca Docker RootDir en un filesystem local soportado. ext4 o XFS configurado correctamente. Evita almacenamiento en red para rutas runtime de overlay2.
Monitoriza tanto uso de disco como uso de inodos. Alerta antes del 85–90% en ambos, no solo GBs.
Estandariza driver y jerarquía de cgroup. Si usas systemd, usa cgroups systemd salvo que haya una razón convincente.
Centraliza logs de denegaciones LSM. AppArmor y SELinux deben aparecer en tu pipeline de logging con filtros, si no depurarás a ciegas.
Baselínea la configuración de hosts y difféala. Versión de kernel, driver de almacenamiento, opciones de montaje, daemon.json. Haz visible la deriva.
Mantén en el runbook una prueba de “contenedor mínimo” de emergencia. La prueba BusyBox/Alpine te dice si el host está fundamentalmente roto.
Documenta excepciones aprobadas de security-opt. Si algunas cargas necesitan ajustes no confinados, trátalo como una decisión de riesgo, no un capricho de desarrollador.

Preguntas frecuentes

1) ¿Qué es OCI en los errores de Docker?

OCI es la especificación Open Container Initiative. En la práctica, Docker usa un runtime OCI (comúnmente runc) para crear namespaces,
cgroups, mounts y luego ejecutar tu proceso. El error significa que la configuración falló.

2) ¿Por qué el error menciona runc o containerd shim?

Docker delega operaciones de runtime a containerd, que usa un shim para gestionar procesos de contenedores. runc realiza las operaciones de bajo nivel
de create/start. Los fallos escalan por esas capas, por eso ves sus nombres en la cadena.

3) ¿Se arregla “OCI runtime create failed” reiniciando Docker?

Ocasionalmente—si el daemon está bloqueado o containerd está inestable. Pero la mayoría de las veces es un problema real del host (espacio, mounts,
políticas, cgroups). Reiniciar puede quitar síntomas temporalmente mientras la causa subyacente permanece.

4) ¿Cómo saber si es un problema de imagen o del host?

Ejecuta un contenedor conocido pequeño. Si docker run --rm busybox true falla, es host/runtime. Si BusyBox funciona pero
tu imagen falla, probablemente es entrypoint, arquitectura, intérprete faltante, mounts o permisos dentro de la imagen.

5) ¿Por qué obtengo “no such file or directory” cuando el fichero existe?

A menudo el entrypoint es un script con shebang apuntando a un intérprete que no existe en la imagen (p. ej. /bin/bash).
Otra causa común es desajuste de arquitectura que produce errores de exec confusos.

6) ¿Cómo provoca la agotación de inodos fallos de OCI create?

Overlay2 crea muchos ficheros y directorios pequeños para metadatos de capas. Si los inodos llegan al 100%, el runtime no puede crear los
directorios necesarios durante mount/setup, así que create falla incluso si todavía tienes GBs libres.

7) ¿Pueden SELinux/AppArmor impedir realmente que los contenedores arranquen?

Sí. El runtime mismo (runc) es un proceso en el host sujeto a la política de seguridad del host. Si la política bloquea mounts, acceso a ficheros
u operaciones concretas, la creación del contenedor falla antes de que tu aplicación se ejecute.

8) ¿Cuál es la forma más segura de “probar si la seguridad es el problema”?

Usa diagnósticos dirigidos: revisa primero logs del kernel/audit. Si debes experimentar, ejecuta un único contenedor de prueba con una anulación específica
(como un perfil seccomp no confinado) y revierte inmediatamente. No cambies ajustes globales como prueba casual.

9) ¿Causa cgroup v2 el OCI runtime create failed?

Puede hacerlo, especialmente con configuración de Docker desalineada o componentes de runtime antiguos. Valida la versión de cgroup y el driver con
docker info y asegúrate de que el host habilite los controladores necesarios.

10) Si overlay2 está roto, ¿puedo cambiar de driver de almacenamiento en el mismo RootDir?

Trátalo como trabajo de migración, no como un interruptor. Cambiar drivers normalmente requiere mover o reconstruir el estado de Docker. Hazlo deliberadamente:
drena cargas, respalda lo que importa (volúmenes) y reconstruye nodos si puedes.

Conclusión: qué hacer la próxima vez

“OCI runtime create failed” es Docker diciendo “el kernel dijo no”, con pasos extra. El camino más rápido es:
captura la cláusula final del error, clasifícala (seguridad/almacenamiento/cgroups/entrypoint) y ve a los logs que realmente pueden confirmarlo.

Siguientes pasos que rinden inmediatamente:

Escribe un snippet de runbook pequeño: prueba BusyBox, docker info RootDir/Driver, df -h y df -i, luego dmesg/journalctl.
Baselínea tus hosts de contenedores: tipo/opciones de filesystem, XFS ftype, modo de cgroup, módulos de seguridad. La deriva es el asesino silencioso.
Deja de almacenar las capas de runtime escribibles de Docker en almacenamientos “ingeniosos”. Usa discos locales para overlay2; usa sistemas de almacenamiento adecuados para datos persistentes.
Cuando el error diga “permission denied”, créelo. Ve directamente a logs AppArmor/SELinux/audit y arregla la política o las etiquetas.