Guía de solución de errores en Docker Compose: 5 fallos frecuentes y cómo resolverlos rápido

Viernes a las 3:30 de la tarde, quedan dos horas para el deadline de commit.

En la terminal, esa línea roja: Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated. Ayer funcionaba perfectamente; hoy no arranca.

Ctrl+C, reintento. Mismo error. Googleo “docker compose port already allocated”, abro cinco o seis hilos de Stack Overflow y pruebo cada solución: reiniciar Docker, borrar contenedores, cambiar puertos… el mensaje de error no se mueve.

Los errores de Docker Compose suelen ocupar decenas de líneas; la frase útil está en la línea 23, pero tú ya te has puesto nervioso en la línea 1. Este artículo resume los problemas que he pisado en los últimos dos años: 5 tipos de errores más frecuentes en Docker Compose, cada uno explicado como “síntoma → causa → solución”. Verás que el 90 % de los errores se resuelven en 5 minutos — si sabes por dónde empezar.

Fundamentos del diagnóstico: domina 3 herramientas clave

Antes de resolver errores concretos, hablemos de las tres herramientas que uso a diario para diagnosticar problemas con Docker Compose.

Herramienta 1: docker-compose ps - ver el estado rápidamente

Este comando te dice qué contenedores están en marcha y cuáles han fallado.

docker-compose ps

Fíjate en la columna State:

• Up - funcionando con normalidad, puedes respirar
• Exit - fallo al arrancar o crash durante la ejecución
• Restarting - reinicios continuos, indica un problema en el comando de inicio

Cuando veo un servicio en estado Exit 1, ya sé que toca revisar los logs.

Herramienta 2: docker-compose logs - buscar pistas en los logs

Esta es la herramienta central del diagnóstico.

# Ver logs de todos los servicios
docker-compose logs

# Solo logs de nginx
docker-compose logs nginx

# Seguimiento en tiempo real (como tail -f)
docker-compose logs -f

# Solo las últimas 100 líneas
docker-compose logs --tail 100 nginx

A veces la salida de logs de Docker es un caos, pero en el 90 % de los casos el error real está en las últimas decenas de líneas. Sube hacia arriba y busca palabras clave como ERROR, failed o cannot.

Herramienta 3: docker inspect - inspección profunda (solo cuando haga falta)

Cuando las dos anteriores no bastan, entra esta.

# Ver la configuración completa del contenedor
docker inspect nombre-contenedor

# Solo el estado
docker inspect --format='{{.State.Status}}' nombre-contenedor

# Ver la dirección IP
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nombre-contenedor

Flujo de diagnóstico general (memorízalo)

Ante un problema, no entres en pánico; sigue este flujo:

1. docker-compose ps - ver qué servicio ha fallado
2. docker-compose logs [nombre-servicio] - buscar el error concreto
3. docker inspect - análisis profundo (la mayoría de veces no hace falta)

Bien, herramientas listas. Ahora vamos con los 5 errores más frecuentes.

Conflicto de puertos - “port is already allocated”

Este error lo he visto demasiadas veces. Verás algo así:

Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated

O bien:

ERROR: for nginx  Cannot start service nginx: driver failed programming external connectivity on endpoint xxx: Bind for 0.0.0.0:80 failed: port is already allocated

¿Por qué ocurre?

Suele deberse a tres situaciones:

1. Tras un docker-compose up, pulsaste Ctrl+C pero no ejecutaste docker-compose down; el contenedor sigue en segundo plano
2. Cambiaste los puertos en docker-compose.yml, pero el contenedor antiguo no se eliminó del todo
3. Otro programa en tu máquina ocupa ese puerto (por ejemplo Nginx o MySQL local)

Soluciones (de simple a compleja, pruébalas en orden)

Solución 1: limpiar y empezar de nuevo (efectiva el 90 % de las veces)

docker-compose down
docker-compose up -d

Para mí esto casi siempre funciona. down detiene todos los contenedores y los elimina, pero conserva los datos de los volumes.

Solución 2: encontrar el contenedor que ocupa el puerto

Si la solución 1 no basta, puede haber un “contenedor fantasma” — uno que no pertenece al proyecto actual pero ocupa el puerto.

# Listar todos los contenedores (incluidos los detenidos)
docker ps -a | grep 8080

# Tras encontrar el container_id, elimínalo
docker stop <container_id>
docker rm <container_id>

Solución 3: revisar procesos docker-proxy

A veces el contenedor se borra, pero el proceso docker-proxy queda colgado.

# Ver procesos docker-proxy
ps aux | grep docker-proxy | grep 8080

# Si hay restos, reinicia el servicio Docker
sudo systemctl restart docker  # Linux
# En Mac: menú Docker Desktop → Restart

Solución 4: comprobar ocupación del puerto en el host

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Puede que sea otro programa local el que ocupa el puerto.

# Linux/Mac
lsof -i :8080
netstat -tlnp | grep 8080

# Windows
netstat -ano | findstr 8080

Si es otro programa, o lo detienes o cambias el puerto en docker-compose.yml.

Solución 5: cambiar la configuración de puertos (cuando no quede otra)

Edita docker-compose.yml:

services:
  web:
    ports:
      - "8081:80"  # cambia 8080 por 8081

Mi recomendación

Acostúmbrate a detener contenedores con docker-compose down, no solo con Ctrl+C. Yo antes siempre pulsaba Ctrl+C por comodidad y cada poco tenía conflictos de puertos; al cambiar el hábito, este error casi desapareció.

En entornos de desarrollo, usa puertos no estándar. En lugar de 80 o 3306, prueba 8080 o 3307 para evitar choques con servicios del sistema.

Problemas de red - “network declared as external but could not be found”

Este error suele verse así:

ERROR: Network my_network declared as external, but could not be found. Please create the network manually using `docker network create my_network` and try again.

¿Por qué aparece?

Docker Compose tiene una trampa habitual: si marcas una red como external: true en docker-compose.yml, Docker asume que ya existe y no la crea. La busca, no la encuentra y falla.

Escenarios frecuentes:

1. Copiaste la configuración de otra persona con una red external que no tienes en local
2. Reiniciaste Docker y se perdió parte de la configuración de redes
3. El nombre de la red tiene mayúsculas/minúsculas mal escritas (¡Docker distingue mayúsculas!)

Soluciones

Solución 1: listar redes existentes y confirmar el nombre

docker network ls

Puede que la red real sea myproject_app_network y no app_network como configuraste. Docker Compose añade automáticamente el prefijo del proyecto.

Solución 2: crear manualmente la red que falta

Si la red no existe, créala:

docker network create my_network

Solución 3: corregir el archivo de configuración

Hay tres formas de arreglarlo; elige una:

# Opción A: quitar external y dejar que Compose la cree
networks:
  app_network:
    driver: bridge

# Opción B: usar name para especificar el nombre exacto
networks:
  app_network:
    external: true
    name: my_actual_network_name

# Opción C: crear la red manualmente y luego referenciarla como external

Yo prefiero la opción A. Salvo que necesites compartir red entre varios proyectos Compose, dejar que Compose gestione la red es más sencillo.

Solución 4: limpiar y reconstruir (cuando se pierden redes tras reiniciar Docker)

docker-compose down
docker network prune  # limpiar redes sin uso
docker-compose up -d

Cómo evitar problemas

• Distingue claramente qué redes deben ser external (compartidas entre proyectos) y cuáles gestiona Compose (uso en un solo proyecto)
• Usa el campo name para fijar el nombre de la red y evitar confusión con prefijos automáticos
• Documenta en el README del equipo las redes external que hay que crear de antemano

Fallo de build - “service failed to build”

Si ves este error, no entres en pánico:

ERROR: Service 'app' failed to build: Build failed

Truco clave: sube en los logs

“service failed to build” es solo un resumen; el problema real está más arriba. Sube 50-100 líneas y busca: ERROR, failed, cannot, not found, permission denied.

La primera vez que me pasó, miré solo la última línea durante un rato. Luego aprendí a subir: el error real podía ser “npm install falló” o “archivo no encontrado”, escondido entre mucha salida.

Subtipos de error frecuentes

Tipo 1: archivo no encontrado

COPY failed: stat /var/lib/docker/tmp/.../package.json: no such file or directory

Causas:

• Ruta de build context incorrecta
• .dockerignore excluye archivos necesarios

Solución:

# Revisar la configuración context en docker-compose.yml
services:
  app:
    build:
      context: ./my-app  # confirma que la ruta es correcta
      dockerfile: Dockerfile

# Renombrar temporalmente .dockerignore para probar
mv .dockerignore .dockerignore.bak
docker-compose build app

Tipo 2: fallo al instalar dependencias

npm ERR! 404 Not Found - GET https://registry.npmjs.org/xxx

O:

E: Unable to locate package xxx

Causas: nombre de paquete incorrecto, versión inexistente, problemas de red

Solución:

# Usar mirror doméstico (en el Dockerfile)
RUN npm config set registry https://registry.npmmirror.com
RUN npm install

# O cambiar fuentes apt
RUN sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list
RUN apt-get update && apt-get install -y xxx

Tipo 3: memoria insuficiente

The command '/bin/sh -c npm install' returned a non-zero code: 137
signal: killed

El código de salida 137 suele indicar falta de memoria.

Solución:

• Docker Desktop → Settings → Resources → Memory, sube a 4 GB o más
• O reduce concurrencia en el Dockerfile: RUN npm install --max_old_space_size=4096

Tipo 4: error de sintaxis en el Dockerfile

Por ejemplo, nombre de instrucción mal escrito o ruta incorrecta en COPY.

Solución: construir por separado para probar:

cd directorio-de-build
docker build -t test-build .

Así verás un mensaje de error más claro.

Métodos de depuración

Reconstruir sin caché:

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

Ver precios →Anuncio

docker-compose build --no-cache service_name

A veces una capa intermedia en caché está corrupta; limpiar y reconstruir lo resuelve.

Ver el contexto de build:

docker-compose config

Muestra la configuración completa parseada por Compose y ayuda a detectar problemas de rutas.

Mi experiencia

• Guarda una versión que construye bien como baseline; prueba cada cambio antes de seguir
• Modifica el Dockerfile poco a poco; si cambias muchas cosas a la vez, no sabrás qué rompió el build
• Si el build es lento, considera multi-stage builds o reordenar instrucciones para aprovechar la caché en lo que cambia menos

El contenedor sale tras arrancar - “exited with code X”

Este caso es más sigiloso: la imagen se construye bien, el contenedor arranca y sale al instante.

Al ejecutar docker-compose ps, verás:

Name              State
app_web_1         Exit 1
app_db_1          Up

Significado de los códigos de salida (memoriza estos)

• Exit 0: salida normal del programa — pero en un contenedor puede ser un problema (el comando terminó y no queda nada en ejecución)
• Exit 1: error de la aplicación (el más habitual)
• Exit 137: memoria insuficiente (OOM) o proceso terminado por kill
• Exit 139: segmentation fault
• Exit 143: señal SIGTERM recibida (normalmente parada manual)

Pasos de diagnóstico

Paso 1: ver los logs

docker-compose logs service_name

En el 90 % de los casos, los logs explican por qué salió.

Paso 2: entrar al contenedor manualmente para depurar

Si los logs no aclaran nada, modifica docker-compose.yml para mantener el contenedor vivo:

services:
  app:
    command: sleep infinity  # evita que salga de inmediato

Luego:

docker-compose up -d
docker-compose exec app sh  # entrar al contenedor
# ejecutar manualmente el comando de inicio original y ver el error

Soluciones según el caso

Exit 0 - el comando termina y el contenedor sale

Por ejemplo, si tu command es echo "Hello", al terminar no queda trabajo y el contenedor sale.

Solución: usa un proceso daemon o un comando bloqueante:

# Ejemplo incorrecto
command: echo "Started"

# Ejemplo correcto
command: npm start  # un proceso que sigue en ejecución

Exit 1 - error de la aplicación

Revisa los logs para localizar la causa. Frecuentes:

• Ruta de archivo de configuración incorrecta
• Variables de entorno faltantes
• Fallo de conexión a la base de datos (aún no está lista)
• Problemas de permisos

Exit 137 - memoria insuficiente

Añade límites de memoria al contenedor:

services:
  app:
    mem_limit: 2g
    memswap_limit: 2g

O ajusta la memoria total asignada a Docker Desktop.

Servicio dependiente no listo

Me pasó: el contenedor de la app arrancaba, pero la base de datos aún se inicializaba y la app fallaba al conectar.

Solución: usa depends_on con healthcheck:

services:
  app:
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Así la app espera a que la base de datos esté realmente lista.

Errores que he pisado

Un contenedor salía una y otra vez con Exit 1; en los logs solo decía “Config file not found”. Busqué un rato: la ruta del archivo de configuración era relativa y el directorio de trabajo dentro del contenedor no era el que yo imaginaba. Al usar ruta absoluta, se solucionó.

Otra vez la contraseña de la base de datos estaba mal; la app fallaba al arrancar y el log lo decía claro, pero no lo leí con atención… perdí 20 minutos en vano.

Problemas de permisos - “permission denied”

Este error es muy habitual al montar volumes:

Error: EACCES: permission denied, open '/app/data/config.json'

O en los logs del contenedor aparece “Permission denied” sin saber qué archivo es.

¿Por qué ocurren problemas de permisos?

El UID/GID del usuario dentro del contenedor no coincide con el propietario del archivo en el host. Por ejemplo:

• En el host el archivo es tuyo (UID 1000)
• Dentro del contenedor la app corre como www-data (UID 33)
• www-data no puede leer/escribir tu archivo y falla

Soluciones

Solución 1: especificar user con UID/GID (recomendada)

Haz que el contenedor corra con tu usuario:

services:
  app:
    user: "${UID}:${GID}"
    volumes:
      - ./data:/app/data

Al ejecutar:

UID=$(id -u) GID=$(id -g) docker-compose up

O en el archivo .env:

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

Empezar ahora →Anuncio

# .env
UID=1000
GID=1000

Solución 2: cambiar permisos en el host

Directo:

chmod -R 777 ./data  # úsalo con cuidado, riesgo de seguridad
# o
chmod -R 755 ./data  # más seguro
chown -R $(id -u):$(id -g) ./data

Solución 3: sistemas con SELinux (CentOS/RHEL) — añadir flag

En CentOS/RHEL puede ser restricción de SELinux:

volumes:
  - ./data:/app/data:z  # permite compartir entre varios contenedores
  # o
  - ./config:/app/config:Z  # solo para este contenedor

La diferencia entre z minúscula y Z mayúscula: minúscula es permiso compartido, mayúscula es exclusivo del contenedor.

Solución 4: usar named volume en lugar de bind mount

Los volumes gestionados por Docker evitan muchos problemas de permisos:

services:
  app:
    volumes:
      - app_data:/app/data  # named volume

volumes:
  app_data:  # Docker gestiona los permisos

La desventaja es que no puedes editar los archivos directamente en el host; solo vía contenedor.

Solución 5: ajustar permisos en un script entrypoint

Para escenarios más complejos:

# entrypoint.sh
#!/bin/sh
chown -R appuser:appuser /app/data
exec "$@"

COPY entrypoint.sh /
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["node", "app.js"]

Mi recomendación

• Producción: usa named volume, más seguro y sin dolores de permisos
• Desarrollo: usa la solución 1 (user con UID/GID) para editar archivos en el host con comodidad
• Evita 777: salvo que confíes plenamente en el código del contenedor, no des permisos 777

Los permisos pueden marear, pero una vez entiendes la lógica de coincidencia UID/GID, dejan de ser un misterio.

Resumen de técnicas generales de depuración

Tras tantos errores concretos, hablemos del enfoque sistemático.

Flujo estándar de diagnóstico (síguelo y acertarás)

1. docker-compose ps           → ver estado, localizar el servicio con problema
2. docker-compose logs <servicio>  → ver logs, encontrar el error clave
3. docker-compose config       → validar sintaxis del archivo de configuración
4. docker inspect <contenedor> → inspección profunda (si hace falta)
5. Prueba aislada              → arrancar solo el servicio problemático

Acostúmbrate a este flujo y no te perderás ante un error.

Comandos de limpieza habituales (mantenimiento periódico)

# Detener y eliminar contenedores (conserva volumes)
docker-compose down

# Eliminar también volumes (¡con cuidado!)
docker-compose down -v

# Limpiar recursos huérfanos (redes, imágenes sin uso, etc.)
docker system prune

# Limpieza profunda (incluye todas las imágenes)
docker system prune -a

# Reconstruir sin caché
docker-compose build --no-cache

# Ver espacio en disco usado por Docker
docker system df

Cada viernes antes de salir ejecuto docker system prune para limpiar la basura acumulada. Una vez vi que Docker ocupaba 50 GB; tras limpiar quedaron 10 GB…

Medidas preventivas (mejor prevenir)

Validación de configuración:

# Antes de arrancar, valida el archivo
docker-compose config

Comprueba la sintaxis YAML y detecta errores de configuración.

Healthcheck:

services:
  web:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Con healthcheck detectas antes si el servicio arrancó pero no está sano.

Política de reinicio razonable:

services:
  app:
    restart: unless-stopped  # recomendado: reinicia salvo parada manual
    # restart: always        # siempre reinicia
    # restart: on-failure    # solo si falla

Variables de entorno centralizadas:

# archivo .env
DB_PASSWORD=your_password
API_KEY=your_key

# docker-compose.yml
services:
  app:
    environment:
      - DB_PASSWORD=${DB_PASSWORD}
      - API_KEY=${API_KEY}

Así cambias configuración sin tocar el YAML y facilitas el trabajo en equipo.

Conclusión

Volvamos al escenario del principio: viernes a las 3:30, deadline cerca, el contenedor no arranca. Ahora ya sabes qué hacer:

1. No entres en pánico, respira
2. Identifica el tipo de error (puerto, red, build, salida, permisos)
3. Sigue las soluciones del capítulo correspondiente, de simple a compleja
4. Si no basta, mira los logs — la respuesta suele estar ahí

Los errores de Docker Compose no asustan; lo que duele es no tener un enfoque sistemático. Recuerda estos 5 tipos y sus soluciones; la próxima vez lo resolverás en 5 minutos.

Último consejo: crea una base de conocimiento del equipo y documenta los problemas y soluciones. En el Wiki de nuestro equipo hay una página de “Problemas frecuentes con Docker” que ayuda a los nuevos a evitar el 80 % de los errores habituales.

¿Qué errores raros de Docker Compose has encontrado? Cuéntalo en los comentarios; quizá le sirva a alguien más.