El daemon de Docker no arranca: lea este registro primero (y luego arréglelo)

enero 21, 2026 • febrero 3, 2026 • Lectura: 27 min • Views: 7

¿Te fue útil?

Cuando el daemon de Docker no arranca, tu host se convierte en una pieza de museo: contenedores congelados en el tiempo, jobs de CI atascados, despliegues que revierten y alguien preguntando si «podemos simplemente reiniciarlo otra vez». Puedes reiniciar, claro. También puedes meter un portátil mojado en el microondas. Ninguno de los dos es una estrategia.

El camino más rápido no es una secuencia aleatoria de reinicios. Es una lectura limpia del registro correcto, seguida de un pequeño número de comandos deliberados que te dicen qué falló: configuración, almacenamiento, características del kernel, reglas de red, permisos o containerd.

Guía de diagnóstico rápido (qué comprobar primero)

Si solo tienes cinco minutos y un pager vibrando en las muelas, haz esto en orden. El objetivo es identificar rápidamente la clase de bloqueo: fallo de parseo de configuración, dependencia de runtime fallida, corrupción/capacidad de almacenamiento, incompatibilidad de características del kernel o fallo de reglas de red.

Primero: systemd dice por qué se negó a mantener Docker vivo

Docker suele gestionarse con systemd. systemd tiene la primera opinión que importa: código de salida y stderr inmediato.

cr0x@server:~$ systemctl status docker --no-pager -l
● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: failed (Result: exit-code) since Tue 2026-01-02 10:12:54 UTC; 17s ago
    Process: 1842 ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=1/FAILURE)
   Main PID: 1842 (code=exited, status=1/FAILURE)
        CPU: 230ms

Jan 02 10:12:54 server dockerd[1842]: failed to start daemon: error initializing graphdriver: overlay2: failed to mount /var/lib/docker/overlay2: invalid argument
Jan 02 10:12:54 server systemd[1]: docker.service: Main process exited, code=exited, status=1/FAILURE
Jan 02 10:12:54 server systemd[1]: docker.service: Failed with result 'exit-code'.
Jan 02 10:12:54 server systemd[1]: Failed to start Docker Application Container Engine.

Decisión: Toma en serio la primera línea failed to start daemon:. Casi siempre indica la clase de causa raíz. Aquí grita «overlay2 mount invalid argument» → incompatibilidad kernel/sistema de archivos/overlayfs, no un «bug de Docker».

Segundo: journalctl para Docker da la pila completa, no solo el titular

cr0x@server:~$ journalctl -u docker -b --no-pager -n 200
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54.118922635Z" level=info msg="Starting up"
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54.152001115Z" level=error msg="failed to mount overlay: invalid argument" storage-driver=overlay2
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54.152114935Z" level=fatal msg="Error starting daemon: error initializing graphdriver: overlay2: failed to mount /var/lib/docker/overlay2: invalid argument"

Decisión: Si ves level=fatal seguido de un subsistema concreto (graphdriver, iptables, daemon.json), deja de adivinar. Pivota a las comprobaciones de ese subsistema.

Tercero: comprueba la capacidad y el sistema de archivos bajo /var/lib/docker

Un disco lleno o la escasez de inodos no siempre se anuncian con cortesía. Simplemente hacen que los daemons se comporten como si hubieran olvidado escribir.

cr0x@server:~$ df -h /var/lib/docker
Filesystem      Size  Used Avail Use% Mounted on
/dev/nvme0n1p4   80G   79G  300M 100% /

cr0x@server:~$ df -i /var/lib/docker
Filesystem      Inodes  IUsed   IFree IUse% Mounted on
/dev/nvme0n1p4   5.0M   5.0M       0  100% /

Decisión: Si los bloques o inodos están al 100%, tu «Docker no arranca» es un incidente de almacenamiento. Libera espacio primero; no cambies drivers, no reinstales paquetes ni «restablezcas Docker» hasta que el host pueda escribir.

Cuarto: valida la configuración del daemon antes de perseguir fantasmas

Una coma final en JSON puede tumbar toda tu plataforma de contenedores. Ojalá fuera una broma. (No lo es.)

cr0x@server:~$ sudo cat /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": { "max-size": "10m", },
  "iptables": true
}

Decisión: Esa coma después de "10m" evitará que dockerd arranque. Corrige el JSON y luego reinicia. No toques nada más.

Quinto: verifica que containerd esté vivo (o confirma que no lo esté)

cr0x@server:~$ systemctl status containerd --no-pager -l
● containerd.service - containerd container runtime
     Loaded: loaded (/lib/systemd/system/containerd.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2026-01-02 10:08:11 UTC; 6min ago
       Docs: man:containerd(8)
   Main PID: 1210 (containerd)

Decisión: Si containerd está abajo, Docker puede fallar con un error de socket o runtime. Arregla containerd primero. Si containerd está sano, sigue adelante.

El único registro que leer primero (y por qué)

Lee el journal de systemd para la unidad docker antes de leer cualquier otra cosa. No porque sea elegante. Porque es autoritativo. Captura:

Por qué systemd dejó de reiniciar el servicio (límites de inicio, bucles de fallos).
Exactamente lo que dockerd imprimió en stderr/stdout.
El tiempo relativo a otros servicios (containerd, red, montajes).

En la mayoría de distros modernas, este es el comando clave:

cr0x@server:~$ journalctl -u docker -b --no-pager -o cat
time="2026-01-02T10:12:54.118922635Z" level=info msg="Starting up"
time="2026-01-02T10:12:54.152114935Z" level=fatal msg="Error starting daemon: failed to load listeners: can't create unix socket /var/run/docker.sock: permission denied"

Decisión: Ese error no es un problema de «Docker no puede hablar con Docker». Es un problema de permisos/propiedad/SELinux/AppArmor en la ruta del socket (o su padre). Ahora sabes la clase de fallo en la que estás.

No empieces con /var/log/docker.log a menos que estés en un sistema que registre explícitamente allí. Muchas instalaciones no lo hacen. No empieces con soluciones aleatorias de Stack Overflow. Tu sistema ya te dijo qué está mal; simplemente no lo has escuchado aún.

Hechos e historia interesantes (para entender los errores)

Docker originalmente usó LXC (Linux Containers) para aislamiento antes de pasar a libcontainer, lo que cambió cómo se consumen las características de bajo nivel del kernel.
containerd se separó de Docker para que el runtime central pudiera evolucionar independientemente; por eso «Docker está caído» puede significar en realidad «containerd está caído».
overlay2 se convirtió en el driver por defecto en muchas distros porque es rápido y eficiente en espacio, pero es exigente con las características del sistema de archivos (especialmente en kernels antiguos).
La integración con iptables no es opcional para la red clásica de Docker; cuando firewalld/nftables/iptables entran en conflicto, Docker puede fallar al arrancar, no solo al ejecutar contenedores.
La adopción de cgroups v2 cambió la canalización de control de recursos; versiones antiguas de Docker en distros nuevas pueden fallar temprano por incompatibilidades con el controlador de cgroups.
Los valores por defecto de logging de Docker (json-file) pueden llenar discos silenciosamente; que el daemon falle al arrancar tras un evento de disco lleno es a menudo crecimiento de logs autoinfligido.
El comportamiento de start-limit es una característica de systemd: tras fallos repetidos, deja de intentar. Los operadores a menudo interpretan esto como «Docker se congeló».
/var/lib/docker no es sagrado; es solo estado. Contiene imágenes, capas, metadatos y volúmenes (según configuración). Se puede migrar, pero hacerlo a la ligera es como ganarse trabajo el fin de semana.
Existe Rootless Docker para reducir privilegios del daemon, pero añade una clase separada de fallos alrededor de servicios de usuario, XDG_RUNTIME_DIR y delegación de cgroups.

Tareas prácticas: comandos, salidas y la decisión que tomas

No arreglas Docker repitiendo «restart». Arreglas Docker recopilando un pequeño conjunto de hechos y tomando una decisión después de cada uno. Abajo están tareas que he usado en incidentes reales, con salidas realistas y lo que significan.

Tarea 1: Confirma el estado de la unidad y la última razón de fallo

cr0x@server:~$ systemctl is-enabled docker; systemctl is-active docker; systemctl status docker --no-pager -l
enabled
failed
● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: failed (Result: exit-code) since Tue 2026-01-02 10:12:54 UTC; 2min 11s ago
    Process: 1842 ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock (code=exited, status=1/FAILURE)
Jan 02 10:12:54 server dockerd[1842]: failed to start daemon: Error initializing network controller: failed to create NAT chain DOCKER: iptables failed

Decisión: Si el fallo apunta al network controller / iptables, no pierdas tiempo en comprobaciones de almacenamiento primero. Ve a la sección de iptables/nftables.

Tarea 2: Extrae los registros completos del arranque para docker

cr0x@server:~$ journalctl -u docker -b --no-pager -n 300
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=info msg="Starting up"
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=info msg="libcontainerd: started new containerd process" pid=1901
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=error msg="iptables failed: iptables -t nat -N DOCKER: iptables v1.8.7 (nf_tables): Chain already exists."
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=fatal msg="Error starting daemon: Error initializing network controller: iptables failed"

Decisión: «Chain already exists» sugiere reglas obsoletas de una ejecución anterior o un conflicto con el backend nftables. Estás en el modo de fallo de reglas de red.

Tarea 3: Comprueba si systemd te está limitando por inicio

cr0x@server:~$ systemctl status docker --no-pager -l | sed -n '1,25p'
● docker.service - Docker Application Container Engine
     Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
     Active: failed (Result: start-limit-hit) since Tue 2026-01-02 10:13:09 UTC; 18s ago
Jan 02 10:13:09 server systemd[1]: docker.service: Start request repeated too quickly.
Jan 02 10:13:09 server systemd[1]: docker.service: Failed with result 'start-limit-hit'.

Decisión: Limpia el start-limit después de arreglar el problema subyacente; de lo contrario «lo arreglas» y seguirá siendo rechazado.

cr0x@server:~$ sudo systemctl reset-failed docker

Tarea 4: Valida /etc/docker/daemon.json sin fiarte de tus ojos

cr0x@server:~$ sudo python3 -m json.tool /etc/docker/daemon.json
Expecting property name enclosed in double quotes: line 3 column 36 (char 61)

Decisión: Corrige la sintaxis JSON primero. Si esto falla, Docker no arrancará. Punto. Tras corregir el fichero, vuelve a ejecutar el validador hasta que imprima JSON formateado y salga 0.

Tarea 5: Extrae la línea de comandos efectiva de Docker (los drop-in importan)

cr0x@server:~$ systemctl cat docker --no-pager
# /lib/systemd/system/docker.service
[Service]
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

# /etc/systemd/system/docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd -H fd:// --data-root /mnt/docker-data --storage-driver=overlay2

Decisión: Si ves overrides, trátalos como sospechosos hasta demostrar lo contrario. Muchos incidentes de «Docker rompió tras una actualización» son en realidad «override antiguo se encuentra con nuevos valores por defecto».

Tarea 6: Comprueba el montaje de data-root de Docker y el tipo de sistema de archivos

cr0x@server:~$ findmnt -no SOURCE,FSTYPE,OPTIONS /var/lib/docker
/dev/nvme0n1p4 ext4 rw,relatime

cr0x@server:~$ findmnt -no SOURCE,FSTYPE,OPTIONS /mnt/docker-data
/dev/sdb1 xfs rw,relatime,attr2,inode64,logbufs=8,logbsize=32k

Decisión: Overlay2 sobre XFS generalmente requiere ftype=1. Si migraste datos de Docker a un XFS formateado con ftype=0, overlay2 fallará.

Tarea 7: Verifica ftype de XFS (crítico para overlay2 en XFS)

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

Decisión: ftype=0 es un paro obligatorio para overlay2. Tu solución es reformatar con ftype=1 (requiere migración de datos) o cambiar el driver de almacenamiento (generalmente un mal día). No sigas reintentando.

Tarea 8: Comprueba soporte del kernel para overlayfs (y detecta causas de «invalid argument»)

cr0x@server:~$ uname -r
4.15.0-213-generic

cr0x@server:~$ lsmod | grep overlay
overlay               102400  0

cr0x@server:~$ sudo dmesg -T | tail -n 20
[Mon Jan  2 10:12:54 2026] overlayfs: filesystem on '/var/lib/docker/overlay2' not supported as upperdir

Decisión: Esa línea en dmesg te dice que el kernel rechazó el sistema de archivos subyacente como upperdir de overlay (común con ciertos sistemas de archivos en red, rutas mal montadas o opciones no soportadas). Arregla el montaje/elección del sistema de archivos; Docker no lo arreglará por ti.

Tarea 9: Confirma el socket y la salud de containerd

cr0x@server:~$ ls -l /run/containerd/containerd.sock
srw-rw---- 1 root root 0 Jan  2 10:08 /run/containerd/containerd.sock

cr0x@server:~$ systemctl status containerd --no-pager -l | sed -n '1,15p'
● containerd.service - containerd container runtime
     Active: active (running) since Tue 2026-01-02 10:08:11 UTC; 6min ago

Decisión: Si falta el socket o containerd falla, arregla containerd antes de Docker. Si containerd está bien, el error de Docker está en otro lado.

Tarea 10: Busca denegaciones obvias de permisos (SELinux/AppArmor aparecen aquí)

cr0x@server:~$ sudo journalctl -b --no-pager | grep -E 'DENIED|apparmor="DENIED"|avc:'
Jan 02 10:12:54 server kernel: audit: type=1400 apparmor="DENIED" operation="create" profile="docker-default" name="/var/run/docker.sock" pid=1842 comm="dockerd"

Decisión: Si ves negaciones explícitas, deja de tratarlo como un problema de configuración de Docker. Arregla la política/perfil o el contexto del archivo. Iniciar Docker con «simplemente desactivar seguridad» es como saltarse las alarmas de humo porque quemaste el pan.

Tarea 11: Inspecciona incompatibilidad del backend de iptables (iptables vs nft)

cr0x@server:~$ sudo iptables --version
iptables v1.8.7 (nf_tables)

cr0x@server:~$ sudo iptables -t nat -S | sed -n '1,25p'
-P PREROUTING ACCEPT
-P INPUT ACCEPT
-P OUTPUT ACCEPT
-P POSTROUTING ACCEPT
-N DOCKER
-N DOCKER-ISOLATION-STAGE-1
-N DOCKER-ISOLATION-STAGE-2

Decisión: Si Docker se queja de cadenas existentes, puede que tengas gestores de reglas en conflicto (firewalld, kube-proxy, scripts personalizados). Decide quién posee las reglas. En caso de apuro, vacía solo las cadenas gestionadas por Docker con cuidado—tras entender el radio de impacto.

Tarea 12: Confirma modo de cgroup y desajuste de driver

cr0x@server:~$ mount | grep cgroup2
cgroup2 on /sys/fs/cgroup type cgroup2 (rw,nosuid,nodev,noexec,relatime)

cr0x@server:~$ journalctl -u docker -b --no-pager | grep -i cgroup | tail -n 5
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=fatal msg="Error starting daemon: Devices cgroup isn't mounted"

Decisión: Esto suele indicar una build antigua de Docker o configuración errónea para cgroups v2. La solución es alinear versiones (actualizar Docker) o configurar el driver/modo de cgroups correcto para tu distro. No lo soluciones desactivando el control de recursos a menos que te guste la ruleta de rendimiento.

Tarea 13: Busca corrupción o escrituras parciales tras cortes de energía

cr0x@server:~$ journalctl -u docker -b --no-pager | tail -n 20
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=error msg="failed to load container metadata" error="unexpected end of JSON input"
Jan 02 10:12:54 server dockerd[1842]: time="2026-01-02T10:12:54Z" level=fatal msg="Error starting daemon: error while opening volume store metadata database"

Decisión: La corrupción de metadatos es real. Ahora decides: recuperar desde backup, eliminar quirúrgicamente el objeto corrupto o reconstruir el estado de Docker. Tu elección depende de si puedes perder imágenes/volúmenes locales.

Tarea 14: Ejecuta dockerd en modo dry-run directamente (útil cuando systemd oculta stderr)

cr0x@server:~$ sudo dockerd --debug --validate --config-file=/etc/docker/daemon.json
unable to configure the Docker daemon with file /etc/docker/daemon.json: the following directives are specified both as a flag and in the configuration file: hosts

Decisión: Tienes fuentes de configuración en conflicto (flags de systemd ExecStart vs daemon.json). Elimina una fuente de verdad. En producción prefiero dejar hosts a systemd y usar daemon.json para ajustes del daemon, no para listeners.

Tarea 15: Comprueba conflictos de puerto (común con flags antiguos de dockerd)

cr0x@server:~$ sudo ss -ltnp | grep -E ':2375|:2376' || true
LISTEN 0      4096         0.0.0.0:2375      0.0.0.0:*    users:(("dockerd",pid=902,fd=7))

Decisión: Si un proceso dockerd antiguo sigue ligado (o otro servicio), tu nuevo daemon no puede enlazar. Mata el proceso sobrante limpiamente y luego arregla la unidad para no lanzar múltiples daemons.

Tarea 16: Libera espacio de forma segura sin destruirlo todo

cr0x@server:~$ sudo du -sh /var/lib/docker/* 2>/dev/null | sort -h | tail -n 10
2.1G	/var/lib/docker/containers
12G	/var/lib/docker/overlay2
18G	/var/lib/docker/volumes

cr0x@server:~$ sudo find /var/lib/docker/containers -name '*-json.log' -size +200M -printf '%p %s\n' | head
/var/lib/docker/containers/2f3.../2f3...-json.log 987654321

Decisión: Si los logs de contenedores son los culpables, trunca logs en lugar de borrar directorios de contenedores.

cr0x@server:~$ sudo truncate -s 0 /var/lib/docker/containers/2f3.../2f3...-json.log

Decisión: Haz que el daemon arranque primero y luego implementa rotación de logs correctamente. Disco lleno es un outage; la higiene perfecta puede esperar una hora.

Los grandes modos de fallo (cómo se ven en los registros)

Las fallas de arranque del daemon de Docker se agrupan en unos pocos buckets. Reconoce el bucket y habrás reducido el incidente a la mitad.