¿Tu contenedor Docker sale al arrancar? Guía completa de diagnóstico (códigos 137/1)

Iba a apagar el ordenador al terminar el día cuando el móvil vibró: alerta de producción. Al abrir la app, los contenedores de cuatro servicios críticos habían pasado todos a Exited. Abrí la terminal y escribí docker ps. Vacío. Completamente vacío.

Es como abrir la nevera para coger una bebida y descubrir que está vacía. Pánico.

Sinceramente, lo primero que pensé fue «se acabó, el fin de semana por el desagüe». Pero al calmarme me di cuenta de que no era la primera vez que veía un fallo al arrancar un contenedor. Solo que esta vez llegó de golpe y el impacto fue mayor.

Tras más de dos horas de diagnóstico, el problema resultó bastante simple: la ruta de un archivo de configuración estaba mal escrita, falló la conexión a la base de datos dependiente y el contenedor salió en cuanto arrancó. Con un flujo sistemático, diez minutos habrían bastado.

Este artículo es la guía de diagnóstico que consolidé después de tropezar mil veces. Tanto si ves Exit Code 1, 137 u otro código, este método te ayuda a localizar la causa raíz con rapidez.

Entender el ciclo de vida del contenedor y los códigos de salida

Antes de diagnosticar, aclaremos una cuestión básica: ¿por qué sale un contenedor?

La esencia del contenedor: ciclo de vida de un proceso

Un contenedor Docker, en el fondo, es un proceso aislado. Mientras ese proceso vive, el contenedor está en ejecución; cuando termina — por salida normal, crash o kill forzado — el contenedor pasa a Exited de inmediato.

Imagina un contenedor web: el proceso principal puede ser nginx o node. Mientras sigue en marcha, docker ps lo muestra. Si sale por cualquier motivo, el contenedor queda Exited.

Por eso a veces docker ps no muestra nada y hay que añadir -a para ver los contenedores ya detenidos.

Tabla rápida de códigos de salida

Cada vez que un contenedor sale, Docker registra un código (Exit Code). Ese número te dice qué ocurrió.

Exit Code 0: todo bien, tarea completada.
Por ejemplo, un script de importación que termina con normalidad. No es un problema.

Exit Code 1: la aplicación falló por sí misma.
Es el código de error más habitual: configuración incorrecta, dependencia faltante, bug en el código, etc.

Recuerdo un despliegue de MySQL atascado en Exit Code 1: tras horas revisando logs descubrí que había cambiado un = por : en la configuración. MySQL detectó el error de sintaxis y se negó a arrancar.

Exit Code 137: memoria insuficiente o terminación forzada.
Dos casos frecuentes:

1. Se superó el límite de memoria y el OOM Killer del kernel Linux mató el proceso
2. Alguien (o el sistema) ejecutó docker kill o kill -9

¿Cómo distinguirlos? Mira OOMKilled con docker inspect. Si es true, es memoria; si es false, probablemente terminación manual.

Exit Code 127: comando no encontrado.
Suele deberse a un CMD o ENTRYPOINT con ruta incorrecta, o a un binario ausente en la imagen.

Exit Code 139: segmentation fault.
Típico en programas C/C++ que acceden a memoria inválida. Raro fuera de capas bajas.

Patrones en los códigos

• 0: salida normal
• 1-128: problema interno de la aplicación (error, configuración, etc.)
• 129-255: intervención externa (señal, kill del sistema, etc.)

Conocer estos rangos ya orienta el diagnóstico.

Diagnóstico en cuatro pasos para localizar el problema

Saber leer un código no basta: hay que excavar con método.

Uso un flujo de cuatro pasos que cubre unos el 90 % de los fallos al arrancar. Siguiéndolo, el problema deja de parecer un misterio.

Paso 1: confirmar el estado del contenedor

Antes de los logs, confirma que el contenedor existe y que está detenido.

docker ps -a

Lista todos los contenedores, incluidos los detenidos. Puntos clave:

CONTAINER ID: identificador único; lo usarás en los siguientes comandos. A menudo bastan los primeros caracteres.

Columna STATUS: un contenedor activo muestra Up X minutes; uno detenido, Exited (código) X minutes ago.

Ejemplo:

CONTAINER ID   IMAGE         STATUS
a1b2c3d4e5f6   mysql:8.0     Exited (1) 2 minutes ago

Código 1 → problema de aplicación; 137 → posible memoria.

Fíjate también en las marcas de tiempo. Si sale en menos de un segundo, suele ser comando de arranque o configuración. Si corre un rato y luego sale, puede ser recursos o dependencias.

Paso 2: revisar los logs del contenedor

Es el paso más decisivo. Antes de salir, el contenedor deja pistas en los logs.

Consulta básica:

docker logs <container_id>

Muestra stdout y stderr. A menudo verás directamente Permission denied, No such file or directory, Connection refused, etc.

Seguimiento en tiempo real (útil al reintentar el arranque):

docker logs -f <container_id>

Como tail -f. Menos útil en un contenedor ya detenido, pero práctico si relanzas para observar el arranque.

Solo las últimas líneas:

docker logs --tail 100 <container_id>

Las últimas líneas suelen bastar.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Con marca de tiempo:

docker logs -t <container_id>

-t añade timestamp a cada línea.

Filtrar errores:

docker logs <container_id> 2>&1 | grep -i error

Para aislar mensajes de error en un flujo largo.

Paso 3: inspeccionar la configuración

Cuando los logs no aclaran, hay que mirar configuración y estado en detalle.

Configuración completa:

docker inspect <container_id>

JSON voluminoso: variables de entorno, montajes, red, etc.

Información concreta:

Código de salida:

docker inspect --format '{{.State.ExitCode}}' <container_id>

OOM Killed:

docker inspect --format '{{.State.OOMKilled}}' <container_id>

Si devuelve true, confirmado: problema de memoria.

Variables de entorno:

docker inspect --format '{{.Config.Env}}' <container_id>

Cadenas de conexión, claves API, etc.

Montajes:

docker inspect --format '{{.Mounts}}' <container_id>

Comprueba rutas de configuración y datos.

Ruta del log en el host:

docker inspect --format='{{.LogPath}}' <container_id>

Si docker logs falla, puedes leer el archivo directamente en el host.

Paso 4: validación con arranque interactivo

¿Los tres pasos anteriores no bastaron? Entra en el contenedor.

Arranque interactivo:

Si antes usabas:

docker run -d my-app

Cambia -d por -it en primer plano:

docker run -it my-app

Verás toda la salida del arranque en directo.

Shell manual:

Si el contenedor sale demasiado rápido:

docker run -it my-app /bin/bash

o:

docker run -it my-app /bin/sh

Dentro puedes:

• Comprobar si existe la configuración: ls /etc/app/config.yaml
• Probar sintaxis: p. ej. mysqld --verbose --help en MySQL
• Ejecutar manualmente el comando de arranque
• Probar conectividad: ping database, telnet redis 6379

Ideal para rutas, permisos y dependencias.

En la práctica, muchos problemas se resuelven en el paso 2. Solo los casos raros requieren los cuatro pasos completos.

Cinco escenarios frecuentes y soluciones

Repasemos los casos más habituales en producción. Los agrupo en cinco categorías que cubren la mayoría de lo que verás.

Escenario 1: error de configuración o ruta inexistente

Síntomas típicos:

• Exit Code 1
• Logs con No such file or directory, config file not found, syntax error, etc.

Caso real:

Desplegué una app Node.js que no arrancaba. El log decía:

Error: ENOENT: no such file or directory, open '/app/config/prod.json'

En docker run había montado:

-v /home/user/config:/app/conf  # ojo: conf

Pero la app leía /app/config. Una letra de diferencia y no encontraba el archivo.

Diagnóstico:

1. docker inspect --format '{{.Mounts}}' para revisar montajes
2. Entrar al contenedor y ls para verificar la ruta
3. Si es sintaxis, la app suele indicar la línea en el log

Solución:

Montaje incorrecto:

# Incorrecto
docker run -v /host/path:/wrong/path my-app

# Correcto
docker run -v /host/path:/app/config my-app

Error de sintaxis:

• YAML: herramienta online o yamllint
• JSON: jq . config.json
• MySQL: mysqld --verbose --help dentro del contenedor

Escenario 2: memoria insuficiente (OOM Killed)

Síntomas típicos:

• Exit Code 137
• docker inspect --format '{{.State.OOMKilled}}' devuelve true
• Logs con Cannot allocate memory, Out of memory, etc.

Caso real:

Una app Java funcionaba en local pero en el servidor de pruebas reiniciaba sin parar. El log:

OpenJDK 64-Bit Server VM warning: INFO: os::commit_memory failed; error='Cannot allocate memory' (errno=12)

Docker Desktop en el servidor de pruebas tenía solo 512 MB y la JVM necesitaba ~600 MB al arrancar.

Diagnóstico:

# Confirmar OOM
docker inspect --format '{{.State.OOMKilled}}' <container_id>

# Memoria del host
free -h

# Uso en tiempo real
docker stats <container_id>

Solución:

Aumentar límite de memoria:

docker run -m 1g my-app
docker run -m 512m --memory-swap 1g my-app

En Docker Desktop:

• macOS: Docker Desktop → Preferences → Resources → Memory
• Windows: Docker Desktop → Settings → Resources → Memory

Optimizar la aplicación:

• Java: java -Xmx512m -jar app.jar
• Node.js: node --max-old-space-size=512 app.js
• Revisar fugas de memoria

En producción:

• Límites acordes a la carga real
• --memory-reservation como límite blando
• Monitorizar tendencia de memoria

Escenario 3: conflicto de puertos

Síntomas típicos:

• Exit Code 1
• Logs con port is already allocated, address already in use, bind: address already in use

Caso real:

El lunes por la mañana docker-compose up no levantaba Nginx:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

El viernes había probado un Nginx local y no lo cerré. El puerto 80 estaba ocupado.

Diagnóstico:

Linux/macOS:

lsof -i :8080
netstat -tuln | grep 8080

Windows:

netstat -ano | findstr 8080

Otros contenedores:

docker ps --format "table {{.Names}}\t{{.Ports}}"

Solución:

Opción 1: cambiar puerto mapeado

# Antes
docker run -p 8080:8080 my-app

# Otro puerto
docker run -p 8081:8080 my-app

Opción 2: detener el proceso que ocupa el puerto

lsof -i :8080
kill -9 <PID>

Opción 3: si es otro contenedor

docker stop <conflicting_container>

Nota: con --network=host, el contenedor usa la red del host directamente; los conflictos de puerto son más probables.

Escenario 4: permisos insuficientes

Síntomas típicos:

• Exit Code 1
• Logs con Permission denied, Operation not permitted, chown: changing ownership failed

Caso real:

MongoDB con datos montados en el host no arrancaba:

chown: changing ownership of '/data/db': Permission denied

El directorio del host era de root y MongoDB en el contenedor corre como usuario mongodb (UID 999).

Diagnóstico:

Permisos en el host:

ls -la /host/data/path

Usuario en el contenedor:

docker run -it my-app /bin/bash
whoami
id

SELinux (CentOS/RHEL):

getenforce

Solución:

Opción 1: ajustar permisos del host

# Solo desarrollo (poco seguro)
chmod 777 /host/data/path

# Más seguro: cambiar propietario
chown -R 999:999 /host/data/path

Opción 2: modo privilegiado (con cuidado)

docker run --privileged=true my-app

No recomendado en producción.

Opción 3: usuario específico

docker run --user 1000:1000 my-app

Opción 4: SELinux

docker run -v /host/path:/container/path:Z my-app
docker run -v /host/path:/container/path:z my-app
setenforce 0  # temporal, no en producción

Escenario 5: dependencias no listas

Síntomas típicos:

• Exit Code 1
• Fallo de conexión a base de datos, timeout a Redis
• Connection refused, ECONNREFUSED, could not connect to server

Caso real:

Con docker-compose, la app dependía de MySQL. Ambos arrancaban casi a la vez y la app fallaba:

Error: connect ECONNREFUSED 172.18.0.2:3306

MySQL estaba «arriba» pero aún inicializando; la app intentó conectar demasiado pronto y salió.

Diagnóstico:

Dependencias en ejecución:

docker ps

Conectividad:

docker exec my-app ping database
docker exec my-app telnet database 3306
docker exec my-app nc -zv database 3306

Red:

docker network ls
docker network inspect <network_name>

Solución:

Opción 1: healthcheck y depends_on en docker-compose

version: '3.8'
services:
  database:
    image: mysql:8.0
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: my-app
    depends_on:
      database:
        condition: service_healthy

Opción 2: reintentos en la aplicación

async function connectWithRetry(maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      await db.connect();
      console.log('Database connected');
      return;
    } catch (err) {
      console.log(`Connection failed, retrying... (${i+1}/${maxRetries})`);
      await new Promise(resolve => setTimeout(resolve, 5000));
    }
  }
  throw new Error('Failed to connect to database');
}

Opción 3: script de espera

COPY wait-for-it.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/wait-for-it.sh
CMD ["wait-for-it.sh", "database:3306", "--", "node", "app.js"]

Opción 4: política de reinicio

docker run --restart=on-failure:3 my-app

En compose:

services:
  app:
    restart: on-failure

Puedes combinar healthcheck + reintentos + restart.

Medidas preventivas y buenas prácticas

Hasta aquí, cómo arreglar cuando ya falló. Configurar bien desde el inicio evita muchos problemas o permite recuperación automática.

Configurar health checks (HEALTHCHECK)

Docker puede comprobar periódicamente si el contenedor funciona de verdad, no solo si el proceso sigue vivo.

En el Dockerfile:

FROM nginx:alpine

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

Para servicios web:

HEALTHCHECK --interval=30s --timeout=5s --start-period=40s \
  CMD curl -f http://localhost:8080/health || exit 1

Bases de datos:

# MySQL
HEALTHCHECK CMD mysqladmin ping -h localhost || exit 1

# PostgreSQL
HEALTHCHECK CMD pg_isready -U postgres || exit 1

# Redis
HEALTHCHECK CMD redis-cli ping || exit 1

Beneficios:

• Orquestadores (Kubernetes/Swarm) reinician o reubican según salud
• depends_on en compose espera servicios realmente listos
• Monitorización puede alertar por estado unhealthy

Ver estado:

docker ps
docker inspect --format='{{.State.Health.Status}}' <container_id>

Política de reinicio

Cuatro estrategias:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

no (por defecto): sin reinicio automático

docker run --restart=no my-app

Para tareas puntuales.

on-failure[:max-retries]: solo si sale con error

docker run --restart=on-failure:5 my-app

Solo reinicia con Exit Code distinto de 0.

always: siempre reinicia

docker run --restart=always my-app

Incluso tras reiniciar el daemon Docker.

unless-stopped: como always, salvo si lo detuviste manualmente

docker run --restart=unless-stopped my-app

La que más uso en producción.

Importante:

1. Regla de 10 segundos: el contenedor debe correr al menos 10 s antes de que aplique la política (evita bucles por mala configuración).
2. Trampa del reinicio infinito: con error de configuración los logs pueden crecer sin límite. Usa rotación de logs.

Cambiar en caliente:

docker update --restart=unless-stopped <container_id>

En docker-compose:

services:
  web:
    image: nginx
    restart: unless-stopped

  worker:
    image: my-worker
    restart: on-failure

Gestión de logs: evitar llenar el disco

Docker guarda logs en JSON por defecto; pueden ocupar decenas de GB. Vi un servidor de producción caer por eso.

Rotación (recomendado) en /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Reinicia Docker:

sudo systemctl restart docker

Máximo ~30 MB por contenedor (10 MB × 3).

Por contenedor:

docker run --log-opt max-size=10m --log-opt max-file=3 my-app

En compose:

services:
  app:
    image: my-app
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Otros drivers: syslog, journald, fluentd, none (no recomendado).

Ver tamaño:

docker inspect --format='{{.LogPath}}' <container_id>
du -h $(docker inspect --format='{{.LogPath}}' <container_id>)

Monitorización y alertas

No esperes al fallo total.

Básico: docker stats

docker stats
docker stats <container_id>

CPU, memoria, red e I/O en tiempo real. Memoria que sube sin parar → posible fuga.

Producción: Prometheus + Grafana

services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"

  cadvisor:
    image: google/cadvisor
    volumes:
      - /:/rootfs:ro
      - /var/run:/var/run:ro
      - /sys:/sys:ro
      - /var/lib/docker/:/var/lib/docker:ro
    ports:
      - "8080:8080"

Alertas por memoria >80 %, reinicios excesivos, etc.

Script simple

#!/bin/bash
EXITED=$(docker ps -a -f "status=exited" --format "{{.Names}}")

if [ -n "$EXITED" ]; then
  echo "Warning: The following containers are exited:"
  echo "$EXITED"
fi

Crontab cada 5 minutos:

*/5 * * * * /path/to/check-containers.sh

Checklist de configuración en producción

version: '3.8'
services:
  web:
    image: my-web-app:latest

    restart: unless-stopped

    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          memory: 512M

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s

    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

    environment:
      - NODE_ENV=production

    ports:
      - "8080:8080"

    depends_on:
      database:
        condition: service_healthy

  database:
    image: postgres:14
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - db-data:/var/lib/postgresql/data
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  db-data:

Con esto, reinicios automáticos, límites de recursos, logs controlados y alertas tempranas.

Conclusión

Lo importante: que un contenedor falle al arrancar no asusta; lo que asusta es no tener un método claro.

Entiende los códigos: 137 → memoria; 1 → configuración o dependencias.

Cuatro pasos:

1. Estado (docker ps -a)
2. Logs (docker logs)
3. Configuración (docker inspect)
4. Validación interactiva (docker run -it)

La mayoría se resuelve en el paso 2.

Cinco escenarios: configuración, memoria, puertos, permisos, dependencias.

Prevención: health checks, restart, rotación de logs, monitorización.

Checklist rápido:

Lista de diagnóstico — contenedor Docker que no arranca

□ Paso 1: docker ps -a — estado y código de salida
□ Paso 2: docker logs <container_id> — logs detallados
□ Paso 3: docker inspect <container_id> — configuración
□ Paso 4: docker run -it <image> — validación interactiva

Localización rápida:
- Exit Code 1 + "No such file" → montajes y configuración
- Exit Code 1 + "port already allocated" → conflicto de puertos
- Exit Code 1 + "Permission denied" → permisos y SELinux
- Exit Code 1 + "Connection refused" → dependencias no listas
- Exit Code 137 + OOMKilled=true → aumentar memoria
- Exit Code 127 → revisar CMD/ENTRYPOINT

Prevención:
□ HEALTHCHECK
□ restart (recomendado unless-stopped)
□ Rotación de logs (max-size + max-file)
□ Límites de recursos (-m)
□ Alertas (docker stats o Prometheus)

Si te sirvió, guárdala para la próxima vez. Y si tuviste un caso raro, compártelo en comentarios.

¡Que tus contenedores sigan Up and Running y no te lleguen alertas un viernes por la noche!