Instalei o n8n e deu erro: como resolver os problemas mais comuns da instalação

Fala aí, beleza? O contêiner subiu, o Docker mostra tudo verdinho, você abre o navegador e… nada 😅

Se tem uma coisa que aprendi vendo gente instalar n8n é que o erro ao instalar n8n quase nunca é criativo

Ele repete quatro motivos: porta ocupada, permissão negada no volume, contêiner que morre sozinho e webhook que não abre

A boa notícia: cada um desses tem sintoma próprio, causa conhecida e correção específica

O problema é que a maioria dos tutoriais assume que deu tudo certo no primeiro run, e quando não dá, você fica olhando pro log sem saber qual pedaço importa

Então bora destrinchar um por um, do sintoma até a correção

Formação Recomendada

Formação Agentes de IA

Domine a criação de Agentes de IA e Venda para Empresas

• 402 aulas
• 32 projetos
• 38h 19min

Conhecer formação

Erro de porta ocupada: o n8n sobe mas o localhost:5678 não abre

Esse é o clássico

O Docker lista o contêiner como rodando, mas http://localhost:5678 não responde

Ou pior: o próprio docker run já falha na hora de publicar a porta

Por que isso acontece:

O n8n roda por padrão na porta 5678, definida pela variável N8N_PORT

Se outra aplicação já ocupa a 5678 na sua máquina (e sim, isso é MUITO comum quando você tem vários contêineres de projetos diferentes), o par porta e host já está tomado

A porta é única por aplicação, não tem como duas coisas escutarem o mesmo lugar

A correção:

A sacada é que a porta de DENTRO do contêiner não precisa mudar

O n8n continua feliz escutando a 5678 lá dentro, você só troca a porta do host que aponta pra ela

docker volume create n8n_data

docker run -it --rm \
  --name n8n \
  -p 5679:5678 \
  -e GENERIC_TIMEZONE="<SEU_FUSO>" \
  -e TZ="<SEU_FUSO>" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

No docker-compose.yml a ideia é a mesma, muda só a sintaxe:

ports:
  - "5679:5678"

Aí o acesso passa a ser http://localhost:5679

Tome cuidado! Depois de remapear, muita gente continua tentando abrir a 5678 e jura que a instalação quebrou de novo 😛

Pra prevenir: decide a porta do host ANTES de subir o contêiner, e anota

EACCES permission denied: o erro de permissão do Docker no n8n

O sintoma aqui é bem literal, a mensagem aparece assim no log:

EACCES: permission denied, open '/home/node/.n8n/config'

Quando bate esse erro, o contêiner nem chega a servir a interface

Por que isso acontece:

A imagem oficial do n8n roda com o usuário node, de UID 1000

Quando você aponta um bind mount pra uma pasta do host que pertence ao root, o processo de dentro do contêiner (que NÃO é root) simplesmente não consegue escrever ali

E o n8n precisa escrever nessa pasta logo de cara, porque é onde ele guarda credenciais, workflows e execuções passadas

E olha, não é caso isolado nem culpa sua: o mesmo erro aparece nas issues #1240 e #11102 do repositório oficial n8n-io/n8n

É o tipo de tropeço que também pega gente instalando outras ferramentas de terminal, tipo o erro ao instalar o Claude Code, onde permissão e caminho de instalação são metade dos casos

A correção:

O caminho mais seguro é não improvisar bind mount pra pasta de dados

Usa volume nomeado, exatamente como está no comando oficial: docker volume create n8n_data e depois monta em /home/node/.n8n

O Docker cuida da permissão pra você e o assunto morre ali

Se você faz questão de apontar pra uma pasta do host (pra fazer backup na mão, por exemplo), então a pasta precisa dar escrita pro UID 1000, senão o erro volta no próximo run

E a variável de permissão do arquivo de settings?

Existe a N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS, booleana, padrão false

Quando ligada em true, ela tenta aplicar permissão 0600 no arquivo de settings, ou seja, leitura e escrita só pro dono

Se liga que são duas coisas separadas: essa variável você liga ou não, e a linha 2.0 trouxe uma mudança própria, os arquivos de configuração passaram a exigir permissão 0600 por padrão

Não é a variável que ativa essa exigência, ela continua vindo desligada, e o comando oficial de instalação já traz ela em true

Ou seja, instalação que era tolerante antes pode reclamar agora

Container do n8n reiniciando sozinho: o que significa o exit code 137

Aqui o sintoma é chato de debugar porque parece intermitente: o contêiner sobe, funciona por um tempinho (ou nem isso) e cai, em loop

E no status aparece o código de saída 137

O que é o 137?

Esse número não é aleatório

O exit code 137 significa que o processo recebeu SIGKILL (sinal 9), tipicamente do OOM killer do kernel Linux por falta de memória

Traduzindo: ninguém derrubou o n8n por bug, o sistema matou o processo porque a memória acabou

Como confirmar:

Dá pra tirar a dúvida na inspeção do contêiner

docker inspect n8n

Na saída, procura a flag OOMKilled

Se ela estiver verdadeira, é falta de memória mesmo, e adiantar pouco ficar mexendo em variável de ambiente: o que precisa é liberar memória pro contêiner

A parte boa dessa história:

Seus dados não vão embora nesse restart

Por padrão o n8n usa SQLite e guarda credenciais, execuções passadas e workflows no diretório .n8n do contêiner, que no comando oficial está montado no volume /home/node/.n8n

Enquanto o volume existe, o contêiner pode morrer e voltar que os workflows continuam lá

Agora, se o contêiner sobe normalmente e o erro aparece só depois, dentro da interface, aí a investigação é outra: vale olhar como corrigir erro 500 no n8n, que é sintoma de aplicação de pé, não de instalação quebrada

Webhook do n8n não abre: URL de teste, URL de produção e proxy reverso

Esse é o erro que mais gera cabelo branco, porque o n8n está rodando, a interface abre, o workflow existe… e o serviço externo chama a URL e nada acontece

Ou então o n8n avisa que aquele webhook já está em uso

São três causas diferentes, cada uma com correção própria

Causa 1: você está usando a URL de teste

O n8n gera DUAS URLs para cada nó Webhook

A Test URL serve pra construir e depurar, ela mostra os dados na tela

A Production URL é a de uso real, e ela não exibe os dados no workflow

O detalhe que pega todo mundo: o webhook de teste fica ativo por 120 segundos depois de acionado

Ou seja, você aciona o Listen for test event, vai configurar o serviço externo com calma, volta e a janela já fechou 😅

O registro também é diferente: o de teste é registrado quando você seleciona Listen for test event ou executa o workflow, e o de produção é registrado quando você publica o workflow

Então a regra de ouro é: publica o workflow ANTES de entregar a URL pro serviço externo

Causa 2: path e método já ocupados

O n8n permite registrar apenas um webhook por combinação de caminho e método HTTP

Ou seja, dois workflows disputando o mesmo GET /my-request não rola, e o n8n avisa que o par já está em uso

A correção é despublicar o workflow que está segurando aquela combinação, ou trocar o caminho do novo

Causa 3: proxy reverso na frente do n8n

Quando o n8n roda atrás de proxy reverso, ele não adivinha sozinho qual é o endereço público

Resultado: ele exibe e registra uma URL que o mundo lá fora não alcança

Pra resolver, a URL do webhook precisa ser definida manualmente, e ela define a base tanto do webhook de teste quanto do de produção

O nome atual da variável é N8N_WEBHOOK_URL

Se você viu WEBHOOK_URL em algum tutorial, ela virou apelido descontinuado: ainda funciona, mas emite aviso de descontinuação na inicialização

Além disso, é preciso informar quantos proxies existem na frente do n8n com a N8N_PROXY_HOPS, sendo 1 para um proxy reverso

E vale ficar de olho na N8N_SECURE_COOKIE, booleana, padrão true: com ela ligada, o cookie de sessão só trafega por HTTPS

Instalei pelo tutorial antigo e quebrou: o que mudou no n8n 2.0

Esse aqui é sorrateiro: o comando não dá erro de digitação, ele só… não existe mais

A linha vigente é a 2.x (a série 2.34 saiu em agosto de 2026), e ela trouxe mudanças que aposentaram receita de tutorial antigo

As principais:

1. --tunnel foi removido na 2.0. Aquela opção de linha de comando pra expor o n8n rapidinho não está mais lá, e a própria documentação manda migrar pra outra solução de túnel, citando ngrok, localtunnel e Cloudflare Tunnel. O erro comum aqui é copiar o comando de um vídeo antigo e achar que o Docker é que está bugado
2. N8N_CONFIG_FILES foi removida na 2.0. A configuração agora migra para variáveis de ambiente, arquivo .env ou configuração baseada em _FILE. Quem tinha arquivo de config apontado por essa variável simplesmente vê a config ser ignorada
3. N8N_RUNNERS_ENABLED está descontinuada da 2.0 em diante. Na 1.x ela era necessária em true pra ligar os task runners, agora não precisa mais ser definida, porque na 2.0 os task runners vêm ligados por padrão e as execuções do nó Code rodam em ambiente isolado
4. N8N_BLOCK_ENV_ACCESS_IN_NODE passou a valer true por padrão. Traduzindo: o acesso a variáveis de ambiente a partir do nó Code está bloqueado por padrão na 2.0. Se um workflow antigo lia env var dentro do Code, ele quebra e o erro nem parece de instalação

A prevenção aqui é simples e vale pra qualquer ferramenta: confere a linha de versão antes de sair copiando comando de tutorial

O que eu vi instalando o n8n com Docker na prática

No vídeo abaixo eu faço a instalação local do n8n com Docker Desktop, que é o caminho mais simples que existe: fora o Docker, você não instala mais nada na máquina

E aí aparecem uns detalhes que só aparecem na tela mesmo

O primeiro é a escolha da imagem

Quando pesquisei dentro do Docker Desktop, vieram vários resultados parecidos, incluindo um de MCP que não tem nada a ver

Tem que ser criterioso pra não baixar a imagem errada e passar meia hora debugando algo que nem é n8n

A imagem que apareceu ali tinha 1 GB de tamanho

O segundo ponto é o volume

Eu criei uma pasta na máquina pra servir de volume antes de subir o contêiner, e o motivo é bem prático: sem volume, você desliga e liga o PC e os dados se foram

E cada imagem exige um caminho específico dentro do contêiner pra gravar os arquivos, então esse caminho tem que ser conferido na documentação da imagem, não chutado

O terceiro é o nome do contêiner

Nomear na mão parece frescura, até você ter cinco contêineres e o Docker ter batizado o seu de um nome aleatório impossível de achar 😀

O quarto é a porta

Eu parti da porta padrão sugerida e já avisei ali: se você tiver outra aplicação Docker rodando na mesma porta, dá conflito, porque a porta é única por aplicação

Depois disso é rodar o run (a imagem baixada vem desligada, quem transforma imagem em contêiner é o run), olhar o log apontando o editor no localhost com a porta escolhida e abrir a interface no navegador

Duas observações que ficaram do processo

A versão instalada não é você que escolhe: a imagem oficial traz a versão estável do momento

E o Docker pode falhar ou simplesmente não abrir quando o PC é ligado de novo

Inclusive, durante a gravação, um dos meus contêineres tinha subido sozinho, sem eu mandar

Ah, e a tela inicial oferece um cadastro por e-mail que libera recursos pagos

Eu pulei porque era uma instalação descartável, mas se a sua vai ficar de pé por muito tempo, vale preencher

No vídeo você vê o ciclo inteiro: busca da imagem, criação do volume, configuração de nome e porta, o run e a primeira tela do n8n no navegador

Próximo passo depois de destravar a instalação

Esses quatro erros (porta, permissão, contêiner morrendo e webhook) cobrem a maior parte dos casos de instalação travada

E o diagnóstico começa sempre no mesmo lugar: o log do contêiner

É ele que diz se você está diante de um EACCES, de um 137 ou de um serviço que nem chegou a subir

O caminho de volta pro trilho é subir de novo com o comando oficial: volume n8n_data montado em /home/node/.n8n, imagem docker.n8n.io/n8nio/n8n e a porta publicada que você escolheu

Abre http://localhost:5678 (ou a porta que você remapeou), confirma que a interface carrega, e SÓ DEPOIS publica o primeiro workflow com webhook

Nessa ordem, quando algo der errado, você sabe exatamente qual peça olhar 😉

até o próximo post!