Ao trabalhar com aplicativos de vários contêineres, você pode se deparar com o erro “network not found” ao executar o comando docker-compose up. Isso impede que seus contêineres iniciem e se comuniquem adequadamente entre si. Este guia explica as razões disso acontecer e as etapas precisas para solucionar a questão.

O Erro

O erro geralmente se parece com isso ao executar 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.

Ou, nas versões mais recentes do Docker Compose V2:

Error response from daemon: network my_custom_network not found

Causa do Problema

Este problema quase sempre está relacionado à forma como as redes são definidas no seu arquivo docker-compose.yml. As causas mais comuns incluem:

  1. Rede Externa Ausente: Você declarou uma rede com a diretiva external: true no seu arquivo compose, mas ainda não a instanciou no Docker.
  2. Erro de Digitação no Nome da Rede: Há uma diferença de escrita entre o nome da rede no arquivo compose e o nome da rede efetivamente existente na engine do Docker.
  3. Redes Órfãs: Ocasionalmente, se o processo do Docker for finalizado bruscamente, o estado virtual da máquina poderá se perder e desincronizar as redes nativas.
  4. Diferentes Contextos do Docker: A rede correspondente foi criada em apenas um contexto de host (um servidor distante) e a configuração local aponta para outro roteamento incorreto.

Solução Passo a Passo

Etapa 1: Verificar se a Rede Existe

Primeiramente, identifique se a rede aguardada pelo Docker de fato está disponível na sua lista de redes. Você pode testar isso visualizando:

docker network ls

Selecione no resultado o nome indicado na mensagem de erro do console. Se ela não existir, significa que o serviço não conseguiu identificá-la.

Etapa 2: Criar a Rede Externa

Caso o seu documento docker-compose.yml peça formalmente uma arquitetura de proxy compartilhada por external (útil, por exemplo, na associação sistêmica multicompose), isso exigirá a intervenção através da criação antes da ativação.

Você pode criá-la inserindo:

docker network create my_custom_network

(Altere os parâmetros do script pelo valor da rede requisitada para my_custom_network).

Nesse estágio de reativação da rede, insira as ordens padrão na inicialização do serviço: docker-compose up -d.

Etapa 3: Modificar docker-compose.yml para Criação Automática

Alternativamente, se você não tem pretensões diretas de associação multissetorial em rede proxy e só desejar ter o ambiente próprio do conteiner na web local, o Docker possui criação espontânea de proxy.

Encontre o bloco descritivo networks presente na base de todo layout oficial:

networks:
  my_custom_network:
    external: true

Edite ou desmarque external: true e aponte os links do driver de forma padrão:

networks:
  my_custom_network:
    driver: bridge

Importante salientar: o modo Docker automático cria pontes diretas cujo prefixo receberá o nome nativo do arquivo de projeto raiz. Sendo assim, a identificação ficará myproject_my_custom_network.

Etapa 4: Limpar as Redes do Docker (Casos de Rede Bugada)

Em cenários adversos nos quais o comando docker network ls retorna informações ativas para a referida rede e, mesmo assim, a tela persistir com erros “network not found”, saiba que provavelmente estamos visualizando conflitos corrompidos ou fragmentados pelo sistema operacional.

O tratamento prático é remover referências inúteis usando a limpeza ativa:

docker network prune

(Cuidado: esta é uma manobra generalista que erradicará do inventário toda e qualquer ponte customizada que esteja estática - isto significa não ativamente em uso por rodapé de conteinêres no exato momento da ordem).

Solução Alternativa: Especificação Nominal Local

O ambiente nativo de contêineres do modelo Docker Compose V2 adicionou a tag inteligente de nomeação expressa na área sem a flag externa. Com a etiqueta name, o formato local e não automático ocorre sob domínio e escolha explícita, eximindo o auto-nomeador dos recursos.

networks:
  my_custom_network:
    name: my_explicit_network_name
    driver: bridge

Deste modo pragmático criaremos nomes independentes locais blindados de atalhos e falhas do contexto prefixado em raízes de repositórios dinâmicos.

Prevenção

Evitando o retorno de dores de cabeça:

  • Exponha Requisitos Sistêmicos: Caso um ambiente de composição local seja amparado de modo estrito via redes preexistentes no terminal, informe as configurações operacionais adequadas via notas num roteiro markdown acessível do arquivo de apoio README.md.
  • Automatização por Scripts Bash: Modelos avançados e repletos de orquestração ganham proteção natural na adição de formulários e códigos do padrão de controle local com makefiles atuando na inserção condutiva sob formato docker network create ... || true para as configurações obrigatórias.
  • Dispense Ociosidades Configutativas Externas: Recomenda-se unicamente configurações do contexto independente a não ser que orquestrações avançadas e externas à modelagem sejam imperativamente indispensáveis ao sistema web isolado de projetos coligados.

Resumo

  • A mensagem alarmante descrevendo a não localização do segmento online (“network not found”) atua confirmando no compose os chamamentos aos quais localmente são inelegíveis.
  • Condicionalmente acoplado à determinação interna external: true cujo acoplador nativo exibe redes ausentes pela esquiva da formatação humana local,
  • Trate configurando via console de modo terminal docker network create <rede>.
  • Como outra via desativa a requisição de busca externa no docker extirpando as dependências ativas sob a formatação external: true.

Artigos Relacionados