Erros no Docker Compose: como diagnosticar e resolver os 5 mais comuns

Sexta-feira, 15h30. Faltam duas horas para o prazo de entrega do código.

No terminal, aparece aquela linha vermelha: Error starting userland proxy: Bind for 0.0.0.0:8080 failed: port is already allocated. Ontem tudo funcionava, mas hoje o ambiente simplesmente não sobe.

Ctrl+C e outra tentativa. O mesmo erro. Você pesquisa “docker compose port already allocated” no Google, abre cinco ou seis tópicos do Stack Overflow e testa todas as soluções: reiniciar o Docker, excluir contêineres, trocar a porta… A mensagem na tela continua exatamente igual.

As mensagens de erro do Docker Compose costumam ocupar dezenas de linhas. A única frase útil pode estar na linha 23, enquanto o desespero começa já na primeira. Este texto reúne os problemas que encontrei nos últimos dois anos: as cinco categorias mais comuns de erro no Docker Compose. Cada uma segue a sequência “sinal do erro → causa → solução”. No fim, você vai perceber que é possível resolver 90% desses casos em cinco minutos — desde que saiba por onde começar.

Fundamentos do diagnóstico — domine três ferramentas essenciais

Antes de tentar corrigir um erro específico, vale conhecer as três ferramentas básicas para diagnosticar problemas no Docker Compose. Uso esses comandos várias vezes por dia.

Ferramenta 1: docker-compose ps — consulte o estado rapidamente

Este comando mostra quais contêineres subiram e quais falharam.

docker-compose ps

Observe a coluna State:

• Up — execução normal; pode respirar aliviado
• Exit — falha na inicialização ou encerramento durante a execução
• Restarting — reinicializações contínuas, sinal de problema no comando de inicialização

Quando vejo um serviço no estado Exit 1, já sei que é hora de abrir os logs.

Ferramenta 2: docker-compose logs — procure pistas nos logs

Esta é a principal ferramenta de diagnóstico.

# Ver os logs de todos os serviços
docker-compose logs

# Ver apenas os logs do nginx
docker-compose logs nginx

# Acompanhar em tempo real, como tail -f
docker-compose logs -f

# Ver apenas as 100 linhas mais recentes
docker-compose logs --tail 100 nginx

Para ser sincero, a saída de logs do Docker às vezes é bem desorganizada. Ainda assim, em 90% dos casos, a mensagem relevante está nas últimas dezenas de linhas. Volte um pouco e procure termos como ERROR, failed, cannot e not found.

Ferramenta 3: docker inspect — análise detalhada, apenas quando necessário

Use este comando quando os dois anteriores não forem suficientes.

# Consultar a configuração completa do contêiner
docker inspect nome_do_container

# Consultar apenas o estado
docker inspect --format='{{.State.Status}}' nome_do_container

# Consultar o endereço IP
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' nome_do_container

Fluxo geral de diagnóstico — memorize esta sequência

Quando algo der errado, mantenha a calma e siga este fluxo:

1. docker-compose ps — descubra qual serviço falhou
2. docker-compose logs [nome_do_serviço] — localize o erro específico
3. docker inspect — aprofunde a análise, se necessário

Agora que as ferramentas estão prontas, vamos às cinco categorias de erro mais frequentes.

Conflito de porta — “port is already allocated”

Já encontrei este erro inúmeras vezes. A mensagem costuma ser parecida com esta:

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

Ou com esta:

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 que isso acontece?

Normalmente, há três possibilidades:

1. Depois do último docker-compose up, você pressionou Ctrl+C, mas não executou docker-compose down, e o contêiner continua rodando em segundo plano
2. Você alterou as portas no docker-compose.yml, mas o contêiner antigo não foi removido por completo
3. Outro programa no computador está usando a porta, como uma instalação local do Nginx ou do MySQL

Soluções — tente da mais simples à mais trabalhosa

Solução 1: limpe e recomece — funciona em 90% dos casos

docker-compose down
docker-compose up -d

Para mim, esta solução quase sempre funciona. O comando down encerra e remove todos os contêineres, mas preserva os dados dos volumes.

Solução 2: encontre o contêiner que está usando a porta

Se a primeira solução não funcionar, talvez exista um “contêiner fantasma”: ele não pertence ao projeto atual, mas continua ocupando a porta.

# Listar todos os contêineres, inclusive os que estão parados
docker ps -a | grep 8080

# Depois de encontrar o container_id, encerrá-lo e removê-lo
docker stop <container_id>
docker rm <container_id>

Solução 3: verifique o processo docker-proxy

Às vezes, o contêiner já foi excluído, mas o processo docker-proxy continua ativo.

# Consultar os processos docker-proxy
ps aux | grep docker-proxy | grep 8080

# Se houver um processo residual, reiniciar o serviço do Docker
sudo systemctl restart docker  # Linux
# No Mac: menu do Docker Desktop → Restart

Solução 4: verifique o uso da porta no host

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

Talvez um programa local esteja usando a porta.

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

# Windows
netstat -ano | findstr 8080

Se encontrar outro programa, encerre-o ou altere a porta no docker-compose.yml.

Solução 5: altere a configuração da porta — como último recurso

Edite o docker-compose.yml:

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

Minha recomendação

Crie o hábito de encerrar os contêineres com docker-compose down, em vez de simplesmente pressionar Ctrl+C. Eu fazia isso por conveniência e enfrentava conflitos de porta com frequência. Depois que mudei o hábito, esse erro praticamente desapareceu.

Outra recomendação é usar portas não padronizadas no ambiente de desenvolvimento. Em vez de expor diretamente as portas 80 e 3306, prefira 8080 e 3307 para evitar conflitos com serviços do sistema.

Problema de rede — “network declared as external but could not be found”

Este erro costuma ter a seguinte aparência:

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 que esse erro aparece?

O Docker Compose tem uma armadilha comum: quando uma rede está marcada como external: true no docker-compose.yml, o Docker presume que ela já existe e não tenta criá-la. Se não a encontrar, retorna o erro.

Cenários frequentes:

1. Você copiou uma configuração que usa uma rede externa, mas essa rede não existe no seu ambiente
2. Você reiniciou o Docker e algumas configurações de rede foram perdidas
3. O nome da rede tem uma diferença entre letras maiúsculas e minúsculas — nomes de rede no Docker diferenciam maiúsculas de minúsculas

Soluções

Solução 1: liste as redes existentes e confirme o nome

docker network ls

Talvez você descubra que o nome real é myproject_app_network, e não app_network, como está na configuração. O Docker Compose adiciona automaticamente o nome do projeto como prefixo.

Solução 2: crie manualmente a rede ausente

Se a rede realmente não existir, crie-a:

docker network create my_network

Solução 3: corrija o arquivo de configuração

Há três opções; escolha uma:

# Opção A: remover external e deixar o Compose criar a rede
networks:
  app_network:
    driver: bridge

# Opção B: usar o campo name para definir explicitamente o nome da rede
networks:
  app_network:
    external: true
    name: my_actual_network_name

# Opção C: criar a rede manualmente e depois referenciá-la com external

Eu prefiro a opção A. A menos que você precise compartilhar uma rede entre vários projetos do Compose, deixar o próprio Compose gerenciá-la dá menos trabalho.

Solução 4: limpe e recrie — quando a rede desaparecer após reiniciar o Docker

docker-compose down
docker network prune  # Limpar redes sem uso
docker-compose up -d

Como evitar o problema

• Diferencie com clareza as redes que devem ser externas, compartilhadas entre projetos, das redes gerenciadas pelo Compose e usadas por um único projeto
• Use o campo name para definir explicitamente o nome da rede e evitar confusão com o prefixo adicionado pelo Compose
• Registre no README da equipe quais redes externas precisam ser criadas previamente, para que quem acabou de entrar não caia nessa armadilha

Falha de build — “service failed to build”

Não se assuste ao ver este erro:

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

Técnica essencial: volte no log

“service failed to build” é apenas um resumo. O problema real apareceu antes. Volte de 50 a 100 linhas e procure palavras como ERROR, failed, cannot, not found e permission denied.

Na primeira vez que encontrei esse erro, fiquei olhando para a última linha por um bom tempo. Só depois percebi que precisava voltar no log. A causa real pode ser uma falha no npm install ou um arquivo ausente, escondida no meio de tanta saída.

Subtipos comuns de erro

Tipo 1: arquivo não encontrado

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

Causas:

• O caminho do build context está incorreto
• O .dockerignore excluiu um arquivo necessário

Solução:

# Verificar a configuração context no docker-compose.yml
services:
  app:
    build:
      context: ./my-app  # Confirmar se o caminho está correto
      dockerfile: Dockerfile

# Renomear temporariamente o .dockerignore para testar
mv .dockerignore .dockerignore.bak
docker-compose build app

Tipo 2: falha ao instalar dependências

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

Ou:

E: Unable to locate package xxx

Causas: nome de pacote incorreto, versão inexistente ou problema de rede.

Solução:

# Usar um registry alternativo no Dockerfile
RUN npm config set registry https://registry.npmmirror.com
RUN npm install

# Ou trocar o mirror do 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: memória insuficiente

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

O código de saída 137 normalmente indica falta de memória.

Soluções:

• No Docker Desktop, acesse Settings → Resources → Memory e aumente o valor para mais de 4 GB
• Ou reduza o paralelismo do build no Dockerfile: RUN npm install --max_old_space_size=4096

Tipo 4: erro de sintaxe no Dockerfile

Pode ser o nome incorreto de uma instrução ou o caminho errado de um arquivo usado por COPY.

Solução: teste o build separadamente.

cd diretorio_de_build
docker build -t test-build .

Assim, você consegue ver uma mensagem de erro mais clara.

Métodos de depuração

Refazer o build sem usar o cache:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

docker-compose build --no-cache service_name

Às vezes, uma camada intermediária do cache está com problema. Limpar o cache e refazer o build pode resolver.

Consultar o contexto de build:

docker-compose config

Este comando mostra a configuração completa interpretada pelo Compose e ajuda a encontrar problemas de caminho.

O que aprendi na prática

• Mantenha como baseline uma versão que faça o build corretamente e teste cada alteração antes de continuar
• Altere uma parte do Dockerfile por vez; se mudar tudo de uma vez, será difícil saber a origem do erro
• Se o build estiver lento, considere um build em várias etapas ou reorganize as instruções para deixar primeiro as que mudam com menos frequência e aproveitar o cache

Contêiner encerrado após iniciar — “exited with code X”

Este caso é mais discreto: o build da imagem termina, o contêiner inicia e logo em seguida é encerrado.

Ao executar docker-compose ps, você verá algo assim:

Name              State
app_web_1         Exit 1
app_db_1          Up

Significado dos códigos de saída — memorize estes

• Exit 0: o programa foi encerrado normalmente — mas, para um contêiner, isso pode ser um problema, pois o comando terminou
• Exit 1: erro na aplicação — o caso mais frequente
• Exit 137: falta de memória (OOM) ou encerramento por kill
• Exit 139: falha de segmentação (segmentation fault)
• Exit 143: recebimento de um sinal SIGTERM — geralmente após uma interrupção manual

Etapas de diagnóstico

Etapa 1: consulte os logs

docker-compose logs service_name

Em 90% dos casos, os logs mostram por que o processo foi encerrado.

Etapa 2: entre manualmente no contêiner para depurar

Se os logs não forem suficientes, altere o docker-compose.yml para manter o contêiner em execução:

services:
  app:
    command: sleep infinity  # Manter o contêiner em execução por enquanto

Depois:

docker-compose up -d
docker-compose exec app sh  # Entrar no contêiner
# Executar manualmente o comando de inicialização original e observar o erro

Soluções específicas

Exit 0 — o comando termina e o contêiner é encerrado

Se o comando for echo "Hello", por exemplo, não restará nada a fazer depois da execução, e o contêiner será encerrado naturalmente.

Solução: use um processo em segundo plano ou um comando bloqueante.

# Exemplo incorreto
command: echo "Started"

# Exemplo correto
command: npm start  # Um processo que continua em execução

Exit 1 — erro na aplicação

Consulte os logs para localizar a causa. Alguns motivos comuns:

• Caminho incorreto do arquivo de configuração
• Variável de ambiente ausente
• Falha na conexão com o banco de dados, porque ele ainda não está pronto
• Problema de permissão

Exit 137 — memória insuficiente

Defina um limite maior de memória para o contêiner:

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

Outra opção é aumentar a memória total atribuída ao Docker Desktop.

Serviço dependente ainda não disponível

Já caí nessa armadilha. O contêiner da aplicação inicia enquanto o banco de dados ainda está sendo preparado; como não consegue se conectar, a aplicação falha.

Resolva com depends_on e 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

Assim, o app espera até que o banco de dados esteja realmente pronto para iniciar.

Problemas que já enfrentei

Certa vez, um contêiner encerrava repetidamente com Exit 1, e o log mostrava apenas “Config file not found”. Depois de muita procura, descobri que tinha usado um caminho relativo para o arquivo de configuração e que o diretório de trabalho dentro do contêiner não era o que eu imaginava. Trocar para um caminho absoluto resolveu.

Em outra ocasião, a senha do banco de dados estava incorreta. A aplicação falhava ao iniciar e o log explicava o motivo, mas eu não o li com atenção e desperdicei 20 minutos.

Problema de permissão — “permission denied”

Este erro é especialmente comum ao montar volumes:

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

Também pode aparecer apenas “Permission denied” no log do contêiner, sem indicar claramente qual arquivo causou o problema.

Por que ocorrem problemas de permissão?

O UID/GID do usuário dentro do contêiner não corresponde ao proprietário dos arquivos no host. Por exemplo:

• No host, o arquivo pertence a você, com UID 1000
• Dentro do contêiner, a aplicação roda como o usuário www-data, com UID 33
• Como www-data não tem permissão para ler ou gravar o arquivo, ocorre o erro

Soluções

Solução 1: defina UID/GID com user — recomendado

Faça o contêiner rodar com o seu usuário:

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

Ao executar:

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

Ou registre os valores no arquivo .env:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

# .env
UID=1000
GID=1000

Solução 2: altere as permissões dos arquivos no host

É uma abordagem direta:

chmod -R 777 ./data  # Use com cuidado: há riscos de segurança
# Ou
chmod -R 755 ./data  # Mais seguro
chown -R $(id -u):$(id -g) ./data

Solução 3: adicione um sufixo em sistemas com SELinux — CentOS/RHEL

Se você usa CentOS/RHEL, a causa pode ser uma restrição do SELinux:

volumes:
  - ./data:/app/data:z  # Permitir o compartilhamento entre vários contêineres
  # Ou
  - ./config:/app/config:Z  # Uso exclusivo deste contêiner

A diferença entre z minúsculo e Z maiúsculo é que o primeiro define permissões compartilhadas, enquanto o segundo define permissões privadas.

Solução 4: use um named volume em vez de um bind mount

Os volumes gerenciados pelo Docker não apresentam o mesmo problema de permissão:

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

volumes:
  app_data:  # Permissões gerenciadas automaticamente pelo Docker

A desvantagem é que você não poderá editar os arquivos diretamente no host; terá de acessá-los pelo contêiner.

Solução 5: ajuste as permissões no script de entrypoint

Esta opção é adequada para casos mais complexos:

# 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"]

Minha recomendação

• Produção: use named volumes; são seguros e evitam o trabalho de ajustar permissões
• Desenvolvimento: use a primeira solução, definindo UID/GID com user, para editar os arquivos diretamente no host
• Evite permissões 777: a menos que confie totalmente no código executado no contêiner, não conceda acesso 777

Permissões podem parecer confusas, mas ficam mais fáceis quando você entende a correspondência entre UID e GID.

Resumo das técnicas gerais de depuração

Depois de tantos erros específicos, vale organizar um método sistemático de diagnóstico.

Fluxo padrão de diagnóstico — siga esta sequência

1. docker-compose ps           → Consultar o estado e localizar o serviço com problema
2. docker-compose logs <serviço> → Consultar os logs e encontrar a mensagem relevante
3. docker-compose config       → Validar a sintaxe do arquivo de configuração
4. docker inspect <contêiner>  → Fazer uma análise detalhada, se necessário
5. Teste isolado               → Iniciar apenas o serviço com problema

Crie esse hábito e você não ficará perdido quando algo falhar.

Comandos comuns de limpeza — faça uma faxina regularmente

# Encerrar e remover contêineres, preservando os volumes
docker-compose down

# Remover também os volumes — use com cuidado
docker-compose down -v

# Limpar recursos sem uso, como redes e imagens
docker system prune

# Fazer uma limpeza completa, incluindo todas as imagens
docker system prune -a

# Refazer o build sem usar o cache
docker-compose build --no-cache

# Consultar o espaço em disco usado pelo Docker
docker system df

Toda sexta-feira, antes de encerrar o expediente, executo docker system prune para remover o que se acumulou durante a semana. Uma vez, descobri que o Docker ocupava 50 GB do disco; depois da limpeza, o uso caiu para 10 GB.

Medidas preventivas — evite o problema antes que apareça

Validação da configuração:

# Validar o arquivo de configuração antes de iniciar
docker-compose config

Este comando verifica a sintaxe do YAML e identifica erros de configuração.

Healthcheck:

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

Com um healthcheck, você descobre mais rapidamente quando um serviço iniciou, mas não está saudável de fato.

Política adequada de reinicialização:

services:
  app:
    restart: unless-stopped  # Recomendado: reiniciar sempre, exceto após uma interrupção manual
    # restart: always        # Reiniciar sempre
    # restart: on-failure    # Reiniciar apenas após uma falha

Gerenciamento centralizado de variáveis de ambiente:

# Arquivo .env
DB_PASSWORD=your_password
API_KEY=your_key

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

Assim, é possível alterar a configuração sem editar o arquivo YAML, o que também facilita a colaboração em equipe.

Conclusão

Voltemos ao cenário do início: sexta-feira, 15h30, o prazo se aproxima e o contêiner não sobe. Agora você sabe o que fazer:

1. Mantenha a calma e respire fundo
2. Identifique a categoria do erro: porta, rede, build, encerramento ou permissão
3. Siga as soluções da seção correspondente, da mais simples à mais complexa
4. Se nada funcionar, consulte os logs — a resposta estará lá

Erros no Docker Compose não precisam ser assustadores. O problema é não ter um método de diagnóstico. Memorize estas cinco categorias e as respectivas soluções; na próxima falha, você poderá resolvê-la em cinco minutos.

Uma última recomendação: crie uma base de conhecimento da equipe e registre os problemas e as soluções já encontrados. Nossa Wiki tem uma página chamada “Problemas comuns do Docker”; depois de lê-la, quem acabou de entrar na equipe evita 80% desses problemas.

Que erros estranhos do Docker Compose você já encontrou? Compartilhe nos comentários; sua experiência pode ajudar outras pessoas.