Al trabajar con aplicaciones multicontenedor, es posible que te encuentres con el error “network not found” al ejecutar docker-compose up. Esto impide que tus contenedores se inicien y se comuniquen entre sí. Esta guía explica por qué sucede esto y proporciona pasos claros para resolverlo.

El Error

El error suele verse así cuando ejecutas docker-compose up:

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

O, en las versiones más recientes de Docker Compose V2:

Error response from daemon: network my_custom_network not found

Causa del Problema

Este problema casi siempre está relacionado con cómo se definen las redes en tu archivo docker-compose.yml. Las causas más comunes son:

  1. Falta la Red Externa: Has declarado una red con external: true en tu archivo compose, pero aún no has creado esa red en Docker.
  2. Error Tipográfico en el Nombre de la Red: Hay una discrepancia entre el nombre de la red declarada en el archivo compose y la red real creada en Docker.
  3. Redes Huérfanas: A veces, si Docker se reinició abruptamente o un desmontaje anterior falló, el estado interno de la red de Docker puede desincronizarse.
  4. Diferentes Contextos de Docker: Creaste la red en un contexto de Docker (como un host remoto) pero estás ejecutando compose en otro (como tu máquina local).

Solución Paso a Paso

Paso 1: Verificar que la Red Existe

Primero, comprueba si la red que Docker Compose está buscando realmente existe. Ejecuta el siguiente comando en tu terminal:

docker network ls

Busca el nombre de la red mencionado en el mensaje de error. Si no está en la lista, entonces no ha sido creada.

Paso 2: Crear la Red Externa

Si tu docker-compose.yml espera una red externa (que a menudo se usa para que varios proyectos compose distintos puedan comunicarse entre sí), debes crearla manualmente antes de iniciar los contenedores.

Crea la red usando:

docker network create my_custom_network

(Reemplaza my_custom_network por el nombre que aparece en tu mensaje de error).

Tras crearla, vuelve a ejecutar docker-compose up -d. Ahora debería funcionar perfectamente.

Paso 3: Modificar docker-compose.yml para Creación Automática

Si realmente no necesitas que la red se comparta con otros proyectos compose independientes, puedes dejar que Docker Compose la gestione automáticamente.

Abre tu docker-compose.yml y mira el bloque networks en la parte inferior:

networks:
  my_custom_network:
    external: true

Cámbialo para que simplemente especifique el controlador, o elimina el parámetro external para que Docker la cree por ti:

networks:
  my_custom_network:
    driver: bridge

Nota: Si Docker Compose crea la red automáticamente, prefijará el nombre de la red con el nombre del directorio del proyecto (ej., myproject_my_custom_network).

Paso 4: Limpiar las Redes de Docker (Si la red debería existir pero falla)

Si docker network ls muestra la red, pero Docker Compose aún afirma que no se puede encontrar, el estado de tu red Docker podría estar corrupto.

Puedes limpiar las redes de Docker no utilizadas e intentarlo de nuevo:

docker network prune

(Advertencia: Esto eliminará todas las redes personalizadas que no estén siendo utilizadas actualmente por al menos un contenedor).

Solución Alternativa: Especificar el Nombre de la Red Explícitamente

Si utilizas Docker Compose V2 y quieres forzar un nombre de red específico sin usar external: true, puedes utilizar la propiedad name:

networks:
  my_custom_network:
    name: my_explicit_network_name
    driver: bridge

Esto indica a Docker Compose que cree la red con ese nombre exacto, ignorando la convención habitual del prefijo de carpeta.

Prevención

Para evitar este error en el futuro:

  • Documenta las Dependencias Externas: Si tu proyecto requiere una red externa, documéntalo claramente en tu archivo README.md.
  • Usa Scripts de Inicialización: Para configuraciones complejas, proporciona un script setup.sh o un archivo Makefile que ejecute docker network create ... || true antes de lanzar docker-compose up.
  • Evita External Cuando no sea Necesario: Mantén las redes de forma interna al archivo compose a menos que necesites explícitamente que abarquen implementaciones separadas.

Resumen

  • El error “network not found” significa que Docker Compose está intentando conectar contenedores a una red que no existe.
  • Por lo general ocurre cuando external: true está configurado en el archivo compose, pero la red no fue creada de forma manual.
  • Soluciónalo creando la red de antemano con docker network create <nombre>.
  • Alternativamente, elimina external: true para permitir que Docker Compose gestione la creación de la red de forma automática.

Artículos Relacionados