Cómo depurar un contenedor Docker que no arranca

Cuando un contenedor Docker no arranca como esperas, la frustración es inmediata. Ves el error, pero no sabes por dónde empezar a debugar. La clave no es reiniciar a ciegas, sino saber dónde buscar los logs y entender los errores comunes. He pasado incontables horas resolviendo estos problemas en producción para mis clientes.

Lo que necesitas es una metodología clara que te permita diagnosticar rápidamente la causa raíz.

Causas por las que un contenedor no arranca

Un contenedor Docker que no arranca no es un fallo único, sino el síntoma de varias posibles causas. Puede ser un problema de configuración, de dependencias, de recursos o incluso de la propia aplicación dentro del contenedor. Mi regla es abordar la depuración de forma sistemática, descartando las causas más obvias primero. Es como diagnosticar una avería en un coche: no empiezas cambiando el motor si la batería está muerta.

Los logs como primera pista

La fuente de información más valiosa cuando un contenedor Docker falla al iniciar son sus logs. Docker captura la salida estándar (stdout) y la salida de error (stderr) de los procesos que corren dentro del contenedor. Acceder a ellos es el primer paso antes de asumir cualquier otra cosa.

docker logs <nombre_del_contenedor_o_id>

Si el contenedor se ha intentado iniciar y ha fallado rápidamente, es probable que los logs ya contengan la razón del problema. Busca palabras clave como “error”, “failed”, “permission denied” o “address already in use”. Estos mensajes suelen ser bastante explícitos sobre la causa raíz.

Errores comunes de arranque y cómo identificarlos

La mayoría de los errores al iniciar un contenedor Docker se repiten en diferentes proyectos. Conocerlos te ahorra tiempo en la depuración. Los problemas de puertos, variables de entorno y configuración de volúmenes son los más frecuentes.

Puerto ya en uso: Si intentas mapear un puerto del host que ya está ocupado por otro proceso, Docker no podrá arrancar el contenedor. Los logs mostrarán un mensaje como “port already in use” o “bind: address already in use”. Necesitas liberar ese puerto o elegir uno diferente para el mapeo.

Variables de entorno incorrectas o faltantes: Muchas aplicaciones dependen de variables de entorno para su configuración. Si una variable esperada no está definida o tiene un valor incorrecto, la aplicación dentro del contenedor fallará al iniciar. Esto suele aparecer como un error de configuración en los logs de la aplicación. Para evitar esto, siempre uso un archivo .env bien estructurado y documentado, como explico en mi guía sobre variables de entorno en Docker.

Volúmenes mal montados o permisos: Si montas un volumen con datos persistentes y la ruta en el host no existe, o el usuario dentro del contenedor no tiene permisos para escribir en esa ruta, el contenedor no arrancará. Los mensajes de “permission denied” o “no such file or directory” son claros indicadores. Verifica las rutas y los permisos de las carpetas en el host.

Configuración de Docker Compose errónea: Un docker-compose.yml con indentación incorrecta, nombres de servicio mal referenciados o dependencias circulares puede impedir que los contenedores se inicien correctamente. El comando docker compose config te ayuda a validar la sintaxis de tu archivo antes de ejecutarlo. Esto me ha salvado de muchos quebraderos de cabeza en producción con clientes que tienen configuraciones complejas.

Depuración interactiva para casos complejos

Cuando los logs no son suficientes, la depuración interactiva es el siguiente paso para entender por qué un contenedor Docker no arranca. Esto implica ejecutar un comando dentro del contenedor o incluso iniciar una shell.

Si el contenedor arranca pero la aplicación falla, puedes usar docker exec para entrar:

docker exec -it <nombre_del_contenedor_o_id> sh

Si el contenedor no llega ni a arrancar, puedes intentar modificar el comando de entrada (entrypoint) para forzarlo a abrir una shell. Por ejemplo, en lugar del comando por defecto, ejecuta sh o bash directamente:

docker run -it --entrypoint sh <imagen>

Una vez dentro, puedes revisar la configuración de la aplicación, comprobar la existencia de archivos, depurar la lógica o verificar las conexiones de red. Es la forma más directa de simular el entorno del contenedor y ver qué falla.

Riesgos y beneficios de la depuración en producción

Depurar un contenedor Docker directamente en producción tiene sus riesgos y beneficios. No es una práctica que recomiende para todos los casos, especialmente si el downtime es crítico.

Lo que ganas:

• Diagnóstico rápido de problemas que solo se manifiestan en el entorno de producción.
• Acceso directo al estado real del sistema, sin depender de logs externos.
• Capacidad de probar soluciones y aplicar parches provisionales al instante.

Lo que complicas:

• Posibilidad de causar más problemas si no se es cuidadoso.
• Los cambios realizados interactivamente no son persistentes y se pierden al reiniciar el contenedor.
• Requiere acceso SSH al servidor y credenciales Docker, aumentando la superficie de ataque.

Mi recomendación es siempre intentar replicar el error en un entorno de staging o desarrollo antes de tocar producción. La diferencia entre debugar a ciegas y con un plan es el tiempo de recuperación. Para asegurar que tus despliegues sean robustos y permitan una recuperación rápida, considera estrategias como los deploys sin miedo al rollback.

La depuración de contenedores es una habilidad clave para cualquier entorno que use Docker. Si quieres profundizar en cómo estructurar tus aplicaciones con esta tecnología, te recomiendo mi artículo sobre Docker Compose para principiantes. También es útil tener una buena estrategia para la gestión de logs en tu VPS para evitar que te quedes sin espacio o pierdas información valiosa. Finalmente, si estás evaluando la arquitectura de tus despliegues, aquí explico por qué uso Docker y Traefik en mis proyectos.