Docker «red no encontrada»: reconstruir redes sin romperlo todo

Qué significa realmente “red no encontrada”

El networking de Docker es, en gran medida, contabilidad. Cuando creas una red, Docker guarda un registro (nombre, ID, driver, ajustes IPAM) en su estado local. Cuando un contenedor arranca, Docker pregunta: “adjuntar este endpoint de contenedor a la red X.” Si Docker no puede encontrar X por ID, obtienes “network not found”.

La parte complicada es que el nombre que ves no es la clave real. Docker usa un ID de red, y Compose almacena/usa ese ID tras bambalinas. Si la entrada de la red se elimina, se corrompe o el estado del daemon se reinicia, Compose puede seguir intentando adjuntar contenedores a un ID ahora inexistente. Así es como terminas con una red que “existe” en tu YAML, “existe” en tu cabeza, pero no en el estado real de Docker.

Dónde aparece el error

• docker run: Error response from daemon: network <id> not found
• docker compose up: fallos durante la creación o el attach del contenedor
• Swarm: tareas bloqueadas con errores de adjunto de red
• Tras un reinicio: el daemon se reinicia y “olvida” redes debido a un directorio de estado roto o una restauración parcial

Importante: “red no encontrada” no es lo mismo que “no se puede alcanzar el servicio”. Esto último suele ser enrutamiento, iptables/nftables, MTU, DNS o configuración de la aplicación. “Red no encontrada” es casi siempre estado del plano de control: Docker no puede localizar un objeto de red que referenciaste.

Verdad irónica: Las redes de Docker son como organigramas. Puedes borrar la casilla, pero todo el mundo sigue intentando reportar a ella.

Lista de diagnóstico rápido (comprueba esto primero)

Este es el orden que minimiza daños colaterales y te lleva del “texto de error” a la “solución” con la menor conjetura. El objetivo no es ser ingenioso; es ser rápido y correcto.

1) Identifica qué está fallando y qué red necesita

Captura el error exacto. ¿Hace referencia a un nombre de red o a un ID hexadecimal? Los IDs delatan que algo guardó una referencia obsoleta.

2) Confirma si Docker cree que la red existe

Si docker network ls no la muestra, no estás ante un problema de paquetes. Estás ante estado faltante.

3) Comprueba si Compose creó y etiqueta una red de proyecto

Las redes de Compose tienen etiquetas como com.docker.compose.project. Si esas etiquetas ya no existen, estás reconstruyendo, no depurando.

4) Revisa la salud del daemon y los logs antes de “arreglar” nada

El estado de red desaparece por razones: disco lleno, corrupción del sistema de archivos, crashes del daemon o una limpieza sobreexigida. Trátalo como un síntoma de un problema mayor hasta que se demuestre lo contrario.

5) Decide el radio de impacto: proyecto único vs host entero

Si solo un proyecto Compose está afectado, no incendies todo el host. Recrea la red del proyecto y vuelve a adjuntar. Si múltiples redes desaparecieron, sospecha daño en el estado del daemon; puede que necesites un reinicio controlado.

Datos interesantes y un poco de historia (porque ayuda)

1. La red “bridge” de Docker es anterior a los flujos modernos de Compose. Docker por defecto usaba el bridge docker0 y NAT por iptables; las redes definidas por el usuario llegaron después para mejorar DNS y aislamiento.
2. Las redes bridge definidas por el usuario incluyen DNS basado en nombres. El servidor DNS embebido (típicamente en 127.0.0.11 dentro de los contenedores) es la razón por la que los contenedores resuelven nombres de servicio sin herramientas adicionales.
3. Compose v2 es un plugin de la CLI de Docker. El paso de una herramienta Python separada a un plugin cambió cómo aparecen los errores y cómo se manejan los contexts.
4. Los IDs de red son identificadores opacos estilo direccionamiento por contenido. Los humanos operan con nombres; el daemon opera con IDs. Perder el mapeo es cómo “pero el YAML dice…” deja de importar.
5. iptables vs nftables ha sido un punto recurrente de dolor. Docker históricamente programaba iptables directamente; en algunas distros el backend de nftables cambia el comportamiento y sorprende a la gente.
6. El estado local de Docker vive bajo /var/lib/docker. Si ese directorio se borra, restaura incompletamente o se monta de forma extraña, las redes “desaparecen” junto con todo lo demás.
7. Las redes overlay se construyeron para la historia multi-host de Swarm. Incluso si nunca usas Swarm, el modelo de redes aparece en cadenas de error y drivers.
8. Existen drivers MACVLAN/IPVLAN para evitar el bridge. Son útiles hasta que tu equipo de red upstream las descubre y pregunta por qué el host no puede hablar con sus propios contenedores.
9. Algunas herramientas de “limpieza” eliminan redes más agresivamente de lo que crees. Cualquier cosa que prunee objetos “no usados” puede competir con reinicios o clasificar recursos como no usados por error.

Una idea para tener en la mesa, atribuida frecuentemente a Werner Vogels: todo falla, todo el tiempo—diseña y opera asumiendo que los componentes se romperán (idea parafraseada).

Causas raíz y modos de fallo comunes

1) La red fue eliminada (a veces «con buena intención»)

Alguien ejecutó docker network rm en redes “no usadas”. O un job de limpieza ejecutó un prune. O un agente CI en un host compartido limpió tras sí mismo y “tras sí mismo” incluyó tus redes.

2) Deriva o corrupción del estado del daemon

Apagado no limpio + problemas de disco + sistema de archivos estresado pueden producir estado parcial. Docker arranca, pero faltan algunos objetos. Las redes suelen ser las primeras bajas porque son metadata-intensivas y referenciadas por IDs a través de múltiples objetos.

3) Cambio de nombre de proyecto Compose o mover directorio

Compose usa el nombre de proyecto (a menudo derivado del directorio) para nombrar recursos. Mueve el directorio o cambia COMPOSE_PROJECT_NAME, y puedes acabar con contenedores que esperan redes creadas bajo el nombre anterior del proyecto.

4) Múltiples contexts de Docker o host equivocado

Crees que estás en producción, pero tu CLI apunta a otro contexto de Docker. La red “falta” porque estás mirando el daemon equivocado. Esto es más común de lo que la gente admite.

5) Swarm y redes overlay en estado medio configurado

Las redes overlay requieren estado de cluster. Si un nodo ya no forma parte del cluster, o el estado del manager está inconsistente, las tareas pueden fallar al adjuntar la red.

6) Firewall/iptables/nftables está roto (pero ese es otro error)

Esto es una distracción común. Reglas NAT rotas normalmente producen fallos de conectividad, no “red no encontrada”. Aun así: un reinicio del daemon puede reprogramar reglas y chocar con cambios de la distro.

Tareas prácticas: comandos, salida esperada y decisiones

Estos son movimientos reales de operador. Cada tarea incluye: el comando, qué significa la salida y qué decisión tomar a continuación. No copies y pegues a ciegas en un host compartido. Lee lo que haces y luego hazlo.

Task 1: Confirmar que hablas con el daemon de Docker correcto

cr0x@server:~$ docker context show
default

Qué significa: Estás usando el contexto default (daemon local). Si muestra otra cosa, podrías estar depurando la máquina equivocada.

Decisión: Si es inesperado, ejecuta docker context ls, cámbiate al correcto y vuelve a comprobar el problema antes de tocar las redes.

Task 2: Verificar que el daemon está sano y responde

cr0x@server:~$ docker info --format '{{.ServerVersion}} {{.OperatingSystem}}'
27.2.0 Ubuntu 24.04.1 LTS

Qué significa: La CLI puede hablar con el daemon y obtener info estructurada. Si esto cuelga o da error, tu problema de networking puede ser un problema del daemon.

Decisión: Si no responde, revisa systemd y los logs primero. No toques redes mientras el daemon esté enfermo.

Task 3: Listar redes y ver qué existe ahora

cr0x@server:~$ docker network ls
NETWORK ID     NAME              DRIVER    SCOPE
1f3a2c1a9e2d   bridge            bridge    local
a9b7b5d41c1f   host              host      local
c3d6f2d51c9a   none              null      local

Qué significa: Solo existen las redes por defecto. Si falta tu red de Compose, esto apoya fuertemente “red eliminada” o “estado perdido”.

Decisión: Si la red objetivo falta, deja de intentar “conectar” contenedores a ella. Planea recrearla.

Task 4: Encontrar la referencia de red desde un contenedor que falla

cr0x@server:~$ docker inspect -f '{{json .NetworkSettings.Networks}}' api_1
null

Qué significa: El contenedor no está adjunto a ninguna red (o no existe). Si el contenedor falló al crear, el inspect puede fallar también.

Decisión: Si el contenedor no existe, mira eventos/logs de Compose; la referencia de red probablemente esté en la salida de error durante la creación.

Task 5: Inspeccionar una red por nombre (si crees que existe)

cr0x@server:~$ docker network inspect app_default
[]
Error response from daemon: network app_default not found

Qué significa: Docker confirma que el objeto de red está ausente.

Decisión: Recrea la red (usualmente vía Compose) en lugar de intentar reparar attachments.

Task 6: Revisar la visión de Compose sobre el proyecto

cr0x@server:~$ docker compose ls
NAME            STATUS              CONFIG FILES
app             running(3)          /srv/app/docker-compose.yml

Qué significa: Docker Compose cree que existe un proyecto. Puede que esté funcionando parcialmente.

Decisión: Si el estado es inconsistente con la realidad, puede haber contenedores huérfanos o redes faltantes. Siguiente paso: docker compose ps.

Task 7: Ver lo que Compose cree que está en ejecución y qué redes espera

cr0x@server:~$ docker compose -p app ps
NAME      IMAGE          COMMAND               SERVICE   STATUS
app-db-1  postgres:16    "docker-entrypoint…"  db        Up 2 hours
app-api-1 app-api:latest "/bin/api"            api       Exit 1

Qué significa: Algunos servicios están en ejecución, otros fallan. Esto ocurre cuando un subconjunto de contenedores está adjunto a una red ahora ausente, o la red desapareció tras reinicios.

Decisión: Revisa los logs y eventos del servicio que falla; confirma que “red no encontrada” es la causa y no un crash de la app.

Task 8: Extraer la razón real del fallo desde los eventos

cr0x@server:~$ docker events --since 10m --filter type=container --filter event=start --filter event=die
2026-01-03T09:11:26.321615241Z container start 5a8c0e3f8b2b (name=app-api-1, image=app-api:latest)
2026-01-03T09:11:26.412992531Z container die 5a8c0e3f8b2b (exitCode=1, name=app-api-1, image=app-api:latest)

Qué significa: El contenedor sí arrancó y luego murió (exit 1). Eso no es “red no encontrada”. El error es a nivel de aplicación.

Decisión: Si los eventos muestran fallos de creación de contenedores (los fallos de attach de red suelen aparecer allí), céntrate en recrear la red. Si muere tras arrancar, depura los logs de la app.

Task 9: Revisar logs del daemon por errores del store de redes o libnetwork

cr0x@server:~$ sudo journalctl -u docker --since "1 hour ago" | tail -n 20
Jan 03 09:03:10 server dockerd[1123]: time="2026-01-03T09:03:10.991132145Z" level=error msg="network sandbox join failed" error="network app_default not found"
Jan 03 09:03:10 server dockerd[1123]: time="2026-01-03T09:03:10.991264223Z" level=error msg="Handler for POST /v1.46/containers/create returned error: network app_default not found"

Qué significa: El daemon falla explícitamente la creación del contenedor debido a que falta la red. Este es el caso de libro de texto.

Decisión: Recrea app_default (preferiblemente vía docker compose up que también la etiqueta correctamente). Evita la creación manual salvo que debas igualar ajustes IPAM.

Task 10: Encontrar quién “posee” una red (las etiquetas importan)

cr0x@server:~$ docker network inspect -f '{{json .Labels}}' app_default
Error response from daemon: network app_default not found

Qué significa: No encontrado, no hay etiquetas para inspeccionar. Cuando existe, las etiquetas te dicen si Compose la creó y qué proyecto.

Decisión: Si la recreas manualmente, pierdes metadata de propiedad de Compose a menos que vuelvas a aplicar etiquetas (no recomendado). Mejor: deja que Compose la cree.

Task 11: Recrear la red de la forma aburrida y correcta (Compose)

cr0x@server:~$ cd /srv/app
cr0x@server:/srv/app$ docker compose -p app up -d
[+] Running 4/4
 ✔ Network app_default  Created
 ✔ Container app-db-1   Started
 ✔ Container app-api-1  Started
 ✔ Container app-web-1  Started

Qué significa: Compose creó la red faltante y arrancó los contenedores. Esta suele ser la solución más limpia.

Decisión: Verifica conectividad y DNS. Si los contenedores siguen fallando con “network not found”, puede que tengas múltiples proyectos o referencias obsoletas; procede a una limpieza más profunda.

Task 12: Validar el driver de la red y el subnet (cazar diferencias silenciosas)

cr0x@server:~$ docker network inspect -f 'Driver={{.Driver}} Subnet={{(index .IPAM.Config 0).Subnet}}' app_default
Driver=bridge Subnet=172.22.0.0/16

Qué significa: Confirma el driver y la configuración IPAM. Si la subred difiere de lo que tus reglas de firewall o listas de permitidos esperan, obtendrás “arranca pero no se comunica con nada”.

Decisión: Si la subred debe ser estable, fíjala en Compose con ipam y recrea intencionalmente, no por accidente.

Task 13: Revisar resolv.conf del contenedor y comportamiento del DNS embebido

cr0x@server:~$ docker exec app-api-1 cat /etc/resolv.conf
nameserver 127.0.0.11
options ndots:0

Qué significa: El DNS embebido está en uso. Si el DNS falla, a menudo es porque el contenedor está en la red equivocada o la red está rota.

Decisión: Si ves un servidor DNS del host en su lugar, puede que estés usando network_mode: host o ajustes personalizados. Eso cambia cómo depuras.

Task 14: Confirmar resolución de nombres entre servicios en la red

cr0x@server:~$ docker exec app-api-1 getent hosts db
172.22.0.2      app-db-1

Qué significa: El DNS funciona y db se resuelve a la IP esperada del contenedor.

Decisión: Si no se resuelve, verifica que ambos contenedores estén en la misma red y que estés usando el nombre de servicio correcto.

Task 15: Mostrar a qué redes está adjunto un contenedor (evita adivinar)

cr0x@server:~$ docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' app-api-1
app_default 

Qué significa: El contenedor está adjunto a app_default.

Decisión: Si un contenedor está en una red distinta a la esperada (como bridge), corrige el archivo de Compose o recrea el contenedor.

Task 16: Detectar endpoints huérfanos y redes “en uso” antes de eliminar

cr0x@server:~$ docker network inspect -f 'Containers={{len .Containers}}' app_default
Containers=3

Qué significa: Tres endpoints de contenedor están adjuntos. Si intentas eliminar esta red, Docker se negará a menos que desconectes o elimines contenedores.

Decisión: Si necesitas reconstruir la red, planifica una parada/controlada y recreación del stack.

Task 17: Parar un proyecto de forma segura y eliminar solo su red

cr0x@server:~$ cd /srv/app
cr0x@server:/srv/app$ docker compose -p app down
[+] Running 4/4
 ✔ Container app-web-1  Removed
 ✔ Container app-api-1  Removed
 ✔ Container app-db-1   Removed
 ✔ Network app_default  Removed

Qué significa: Se eliminan los contenedores del proyecto y su red por defecto. Los volúmenes permanecen a menos que usaras -v.

Decisión: Este es el método seguro para reconstruir cuando la red está corrupta o mal configurada. Siguiente: docker compose up -d para recrearla.

Task 18: Confirmar que iptables/nftables no ha sido neutralizado silenciosamente

cr0x@server:~$ sudo iptables -S DOCKER | head -n 5
-N DOCKER
-A DOCKER -i docker0 -j RETURN
-A DOCKER ! -i docker0 -p tcp -m tcp --dport 5432 -j DNAT --to-destination 172.22.0.2:5432

Qué significa: Las cadenas iptables de Docker existen. Si la cadena DOCKER falta o está vacía en un host que depende de puertos publicados, la conectividad fallará aun si la red existe.

Decisión: Si las cadenas faltan tras un reinicio del daemon, revisa la configuración del daemon, el gestor de firewall y si el host usa el backend nftables con reglas incompatibles.

Broma #1: Si arreglas el networking de Docker reiniciando, no lo arreglaste—simplemente apostaste y ganaste esta vez.

Cómo reconstruir redes sin romperlo todo

Principio 1: Prefiere recrear redes con la herramienta que las creó

Si Compose creó la red, deja que Compose la recree. Compose aplica etiquetas y convenciones de nombres que mantienen las operaciones futuras predecibles. docker network create manual está bien para experimentos puntuales; en stacks de producción es la forma de fabricar misterios.

Principio 2: Contén el radio de impacto

Hay tres ámbitos de intervención:

• Ámbito del proyecto: Recrea app_default y solo los contenedores del proyecto.
• Ámbito del host: Repara redes por defecto (bridge/docker0) y la programación de iptables. Más arriesgado.
• Reinicio del estado del daemon: Último recurso; puede destruir todo el estado de Docker en el host.

Reconstrucción a nivel proyecto: la solución común más segura

Si obtienes “red no encontrada” para una red gestionada por Compose, haz esto:

1. Confirma el nombre de red que Compose espera (a menudo <project>_default).
2. Ejecuta docker compose up -d en el directorio correcto y con el nombre de proyecto correcto. Esto debería recrear la red si falta.
3. Si los contenedores están atascados o medio creados, haz docker compose down y luego up -d.

¿Cuándo no arregla docker compose up -d? Cuando tienes recursos obsoletos con nombres en conflicto, nombres de proyecto desajustados, o redes externas referenciadas que no están creadas.

Redes externas: donde los humanos se ponen trampas

Compose soporta external: true. Eso significa “Compose no creará esta red”. Si la red falta, Compose fallará—y con razón. Este es el escenario donde los operadores juran que Compose está roto. No lo está. Tú le dijiste que no creara la red.

Si tu stack usa redes externas, tu trabajo es asegurarte de que existan y tengan configuración estable (subnet, driver) a través de reconstrucciones del host. Si no puedes garantizar eso, deja de usar redes externas a menos que haya una razón real.

Recreación manual (solo cuando debas)

A veces no puedes ejecutar Compose (CI caído, repo inaccesible, o necesitas un puente temporal para levantar servicios críticos). En ese caso, recrea manualmente con cuidado:

• Iguala el driver (bridge, overlay, macvlan).
• Iguala ajustes IPAM si algo depende de rangos fijos.
• Sé consciente de que las etiquetas y la propiedad de Compose no estarán, lo que afecta a docker compose down después.

cr0x@server:~$ docker network create --driver bridge --subnet 172.22.0.0/16 app_default
b9a1f1a2a3c4d5e6f7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8

Qué significa: Creaste una red bridge con una subred fija.

Decisión: Usa esto solo como medida temporal. Una vez estable, vuelve a la creación gestionada por Compose para evitar deriva.

Reconstruir el bridge por defecto (docker0) sin caos

Si el error trata sobre la red bridge o docker0 falta/está rota, estás en territorio a nivel host. Síntomas: contenedores no arrancan incluso con networking por defecto, o puertos publicados dejan de funcionar después de upgrades.

Procede como adulto:

• Programa una ventana si el host corre algo importante.
• Detén cargas de trabajo limpiamente (Compose down, Swarm drain, lo que aplique).
• Reinicia Docker y valida docker0, rutas y cadenas iptables.

cr0x@server:~$ ip link show docker0
3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default
    link/ether 02:42:8f:aa:bb:cc brd ff:ff:ff:ff:ff:ff

Qué significa: La interfaz existe. El estado DOWN es normal si no hay contenedores adjuntos.

Decisión: Si docker0 no existe, sospecha configuración del daemon que deshabilita la creación del bridge, o un directorio de estado corrupto.

Reinicio del estado del daemon: último recurso, herramienta muy afilada

Si las redes desaparecen con frecuencia, o Docker se niega a crear nuevas, puedes estar ante un /var/lib/docker corrupto (o problemas con el driver de almacenamiento). La solución puede ser borrar el estado de Docker y volver a desplegar cargas desde la fuente de la verdad. Eso no es “reconstruir la red”. Es “reconstruir el nodo”.

No improvises esto en un servidor pet que contenga la única copia de tus volúmenes. Si no estás seguro, para e inventaría qué datos están dónde.

Broma #2: “docker system prune -a” no es un plan de mantenimiento; es una prueba de carácter.

Tres mini-historias del mundo corporativo (dolor incluido)

Mini-historia 1: El incidente causado por una suposición equivocada

Una empresa mediana ejecutaba algunas apps internas en una sola VM potente. El equipo usaba Docker Compose, y funcionó tan bien que nadie tocó la sección de redes durante meses. Entonces un ingeniero añadió external: true a una red porque quería que dos proyectos Compose compartieran la red del reverse proxy.

Asumieron que “external” significaba “compartida entre proyectos” y que Compose la crearía si faltaba. Desplegaron una nueva VM desde una imagen, ejecutaron docker compose up -d, y vieron el fallo inmediato: “network proxy_net not found.” El on-call hizo lo que hacen los on-calls: reintentó, reinició Docker, reintentó otra vez.

La caída no fue el error en sí; fue la respuesta. Bajo presión, crearon la red manualmente—pero usaron una subred diferente a la del host antiguo. El reverse proxy arrancó, pero listas de permitidos internas y un par de comprobaciones de monitorización con rutas codificadas esperaban el rango anterior. Mitad del tráfico quedó “misteriosamente” bloqueado por una regla de firewall pensada para proteger una base de datos.

La solución fue simple y dolorosamente educativa: crear la red externa explícitamente y fijar su subred en código de infraestructura, no en la memoria de alguien. Luego reconstruir el host de forma controlada para que la configuración de red no dependiera de quién la tecleara.

Mini-historia 2: La optimización que salió mal

Otra organización quería “despliegues más rápidos” y reducir uso de disco. Alguien añadió un job nocturno que ejecutaba un prune para borrar objetos Docker no usados. Recuperó espacio—hasta que dejó de hacerlo.

El job corrió en un periodo tranquilo cuando un stack Compose se estaba redeployando. Por una breve ventana, los contenedores se detuvieron y las redes parecieron “no usadas”. El prune borró una red bridge definida por el usuario que estaba a punto de ser reutilizada segundos después. El despliegue siguió, y los contenedores fallaron al arrancar: “network not found.” La alerta se retrasó porque los health checks solo corrían cada pocos minutos. Gran timing.

Lo “arreglaron” volviendo a ejecutar el despliegue, que recreó la red. Pero el daño real fue que el job de prune permaneció. Semanas después, el mismo patrón volvió a ocurrir, esta vez durante una ventana de cambios más grande. El segundo incidente fue más largo porque los ingenieros persiguieron fantasmas de iptables y DNS que no eran el problema.

La corrección eventual fue aburrida: hacer prune solo con filtros explícitos, nunca en hosts compartidos y nunca sin revisar despliegues en curso. También movieron cargas a un sistema donde los nodos efímeros hicieron irrelevante la limpieza. La velocidad mejoró. No porque prune fuera ingenioso, sino porque la plataforma dejó de ser frágil.

Mini-historia 3: La práctica aburrida pero correcta que salvó el día

Un equipo afín a finanzas tenía una regla: cada proyecto Compose debe declarar sus redes con nombres explícitos y rangos IPAM, y cada red externa debe ser creada por un paso de aprovisionamiento antes de cualquier despliegue. La regla molestaba a los desarrolladores, lo cual suele ser señal de que está haciendo algo útil.

Un día un host perdió el estado de Docker tras un incidente de disco. Las redes desaparecieron. Los contenedores desaparecieron. Todos tuvieron una mala tarde. Pero el runbook de redeploy no implicó conjeturas: aprovisionar redes externas, desplegar stacks Compose, verificar conectividad. Porque las subredes estaban fijadas, las reglas de firewall y monitorización no necesitaron ediciones de emergencia.

La recuperación no fue mágica; fue predecible. Su runbook también incluía “verifica que estás en el contexto Docker correcto” y “vuelca docker info y journalctl en el ticket del incidente.” Eso significó menos folklore y más evidencia.

Siguieron teniendo un incidente. Simplemente no tuvieron un segundo incidente autoinfligido encima. En operaciones, eso es ganar.

Errores comunes: síntoma → causa raíz → solución

1) Síntoma: “network <hex> not found” tras mover un directorio de proyecto Compose

Causa raíz: Cambió el nombre del proyecto, los recursos antiguos referenciados por ID ya no existen, o invocas Compose con un valor -p diferente.

Solución: Ejecuta Compose con el nombre de proyecto original si quieres reutilizar recursos, o ejecuta docker compose -p <name> down (si es posible) y vuelve a desplegar con el nuevo nombre de forma consistente.

2) Síntoma: Compose falla solo en una red marcada como external

Causa raíz: La red externa no está creada (por diseño, Compose no la crea).

Solución: Créala explícitamente (idealmente via aprovisionamiento/automatización) y fija subnet/driver para que coincida con las expectativas.

3) Síntoma: “red no encontrada” aparece tras un job de limpieza o evento de presión de disco

Causa raíz: Un prune automático eliminó redes, o el estado de Docker se perdió parcialmente por disco lleno/corrupción.

Solución: Elimina/limita jobs de limpieza; reconstruye redes vía Compose; investiga la salud del almacenamiento del host y la durabilidad del estado de Docker.

4) Síntoma: La red existe, pero contenedores nuevos no pueden adjuntarse; los errores mencionan sandbox/join

Causa raíz: Endpoints obsoletos, pares veth sobrantes o inconsistencia interna de daemon/libnetwork tras crashes.

Solución: Reinicio controlado del proyecto (compose down/up). Si persiste entre proyectos, reinicia Docker en una ventana; si sigue roto, planea reconstruir el nodo.

5) Síntoma: Puertos publicados dejan de funcionar, pero no hay “red no encontrada”

Causa raíz: Programación de iptables/nftables rota; el gestor de firewall sobrescribió las cadenas de Docker.

Solución: Arregla la integración del firewall; reinicia Docker después de corregir; valida cadenas DOCKER y reglas NAT.

6) Síntoma: No ves la red, pero tus compañeros sí

Causa raíz: Contexto Docker equivocado, host equivocado o sesión SSH al entorno incorrecto.

Solución: Verifica contexto y endpoint; estandariza prompts de shell; requiere indicadores de entorno explícitos en los runbooks.

Listas de verificación / planes paso a paso

Checklist A: Un stack Compose falla con “red no encontrada”

1. Confirma contexto Docker e identidad del host (evita depurar la máquina equivocada).
2. No hagas prune de nada. Primero, recoge evidencia:
   • docker network ls
   • docker compose -p <proj> ps
   • sudo journalctl -u docker --since "1 hour ago"
3. Si la red faltante es la por defecto del proyecto: ejecuta docker compose up -d desde el directorio correcto.
4. Si aún falla: ejecuta docker compose down (sin volúmenes) y luego docker compose up -d.
5. Valida: docker network inspect (driver/subnet), docker exec ... getent hosts ....
6. Si vuelve a ocurrir: encuentra y mata el proceso que está eliminando redes (job de limpieza, hábito humano, agente CI).

Checklist B: Múltiples proyectos afectados o redes por defecto faltan

1. Asume un problema a nivel host hasta que se demuestre lo contrario.
2. Revisa logs del daemon por errores de almacenamiento/estado; comprueba espacio en disco y salud del sistema de archivos.
3. Programa una ventana de mantenimiento (sí, incluso si es “solo networking”).
4. Detén cargas de trabajo limpiamente.
5. Reinicia Docker; confirma que docker0 existe y que las cadenas iptables están presentes.
6. Si el estado está claramente corrupto: reconstruye el nodo desde la fuente de la verdad en lugar de editar /var/lib/docker a mano.

Checklist C: Estrategia de redes externas que no te morda después

1. Usa redes externas solo cuando realmente necesites conectividad cross-proyecto.
2. Créalas en código de aprovisionamiento, no en el historial del terminal de una persona.
3. Fija subnet y driver y documenta por qué.
4. Valida con un contenedor desechable: adjunta, resuelve nombres, accede a puertos esperados.
5. Audita jobs de limpieza: las redes externas nunca deben ser pruneadas automáticamente en hosts compartidos.

Preguntas frecuentes

1) ¿Por qué Docker se queja de un ID de red en vez de un nombre?

Porque internamente Docker referencia redes por ID. Los nombres son para humanos. Stacks y contenedores a menudo almacenan el ID, así que cuando el ID desaparece obtienes una pista con forma de hexadecimal.

2) ¿Puedo simplemente recrear una red con el mismo nombre y listo?

A veces sí. Pero si un contenedor referencia el antiguo ID de red, recrearla por nombre no ayudará hasta que el contenedor sea recreado o re-adjuntado. La forma más segura es dejar que Compose recree tanto la red como los contenedores afectados.

3) ¿Recrea docker compose up -d redes faltantes automáticamente?

Sí para redes que gestiona (no externas). Si la red está marcada como external: true, Compose no la creará y fallará si falta.

4) ¿Cuál es la forma más segura de reconstruir una red Compose rota?

docker compose down (sin -v a menos que lo desees), luego docker compose up -d. Eso limpia contenedores y la red de proyecto y recrea de forma limpia.

5) ¿Eliminar una red borrará mis datos?

Eliminar una red no borra volúmenes. Pero si tus datos viven dentro del filesystem del contenedor (sin volumen), eliminar contenedores los eliminará. Haz inventario de tus volúmenes antes de “limpiar”.

6) ¿Cómo sé si un job de limpieza causó esto?

Revisa systemd timers/cron, scripts CI e historiales de shell. También mira las marcas temporales en los logs del daemon: un “network removed” repentino o una brecha seguida de redes faltantes es una señal fuerte.

7) ¿Puede “red no encontrada” ser causado por iptables o reglas de firewall?

No típicamente. Los problemas de firewall causan problemas de conectividad, no errores de objeto faltante. Si el daemon dice “not found”, no puede localizar el objeto de red en su estado.

8) ¿Y si esto es Swarm y redes overlay?

Entonces necesitas confirmar la salud del cluster Swarm. Las redes overlay dependen del estado del manager. Un nodo que salió del cluster o un quorum de managers roto puede hacer que las tareas fallen al adjuntar la red. Arregla el estado del cluster primero y luego redeploya servicios.

9) ¿Cómo prevengo que esto vuelva a pasar?

Deja de ejecutar jobs agresivos de prune en hosts compartidos, fija la configuración de red cuando la estabilidad importe y trata /var/lib/docker como estado duradero que necesita higiene de disco y monitorización real.

Próximos pasos que deberías hacer

Cuando Docker dice “red no encontrada”, créetelo. No pierdas el tiempo depurando paquetes para un objeto de red que no existe.

1. Haz el diagnóstico rápido: confirma contexto, confirma que la red falta, revisa logs del daemon.
2. Arregla con el menor alcance posible: recrea vía Compose para ese proyecto; evita reinicios a nivel host.
3. Si esto se repite, trátalo como un problema de sistemas: jobs de limpieza, salud de disco, estabilidad del estado del daemon y aprovisionamiento repetible de redes externas.
4. Escribe el runbook que desearías tener hoy: comandos para verificar estado y la secuencia exacta “down/up” que es segura para tu stack.

Reconstruir redes sin romperlo todo no se trata de heroísmos. Se trata de saber qué capa está rota y negarse a “optimizar” hasta provocar nuevos outages.