n8n com problemas? Veja os erros mais comuns e como corrigir
n8n fora do ar, webhook falhando ou workflow com erro? Veja como diagnosticar Docker, PostgreSQL, Redis, filas, APIs e automações com IA.
Por que o n8n pode parar mesmo quando o workflow parece correto
O n8n conecta sistemas, APIs e bancos de dados em workflows que podem executar com pouco código ou com lógica personalizada. Em uma instalação n8n self-hosted, porém, a automação também depende de Docker, servidor, banco, rede, proxy reverso, certificados e serviços externos.
Por isso, dizer apenas que o n8n não funciona ainda não identifica a causa. Um workflow pode falhar porque recebeu dados diferentes, porque uma credencial expirou ou porque uma API mudou. A instância inteira pode ficar indisponível por falta de memória, disco cheio, PostgreSQL inacessível ou erro após uma atualização.
O diagnóstico começa separando quatro camadas: a execução do workflow, as integrações externas, os componentes do n8n e a infraestrutura. Essa separação evita alterar containers e bancos quando o erro está em um único campo do payload — e evita editar o workflow quando o problema real é a VPS.
Workflow n8n com erro: comece pela primeira falha
Abra a execução afetada e localize o primeiro nó vermelho. A mensagem desse nó, sua entrada e sua saída normalmente oferecem mais informação do que os erros posteriores. Se um nó deixou de produzir um campo, todos os passos que dependem dele podem falhar em sequência.
Formato de entrada inesperado
O nó esperava uma lista, texto ou objeto, mas recebeu outra estrutura. Compare uma execução funcional com a execução que falhou e observe tipos, caminhos e quantidade de itens.
Campo vazio ou ausente
Expressões podem retornar null ou undefined quando o evento não contém o campo esperado. Trate campos opcionais e valide a entrada antes de usá-la.
Credencial expirada
Tokens OAuth, chaves e senhas podem expirar, ser revogados ou pertencer ao ambiente errado. Reautentique somente após confirmar a resposta do serviço.
API indisponível ou limitada
Timeouts, erros 5xx e respostas 429 indicam falha externa, sobrecarga ou limite de requisições. Retentativas precisam de intervalo e limite.
Expressão incorreta
Referência a um nó renomeado, item inexistente ou caminho antigo pode quebrar o mapeamento. Avalie a expressão com os dados reais daquela execução.
Erro em código personalizado
O Code node pode falhar por exceção, biblioteca indisponível, retorno inválido ou diferença no número de itens. Registre e trate os casos de entrada esperados.
Resposta da API mudou
Um fornecedor pode renomear campos, alterar paginação ou devolver um erro com estrutura diferente. Salve o status HTTP e o corpo bruto para comparar.
Nó ou versão desatualizada
Mudanças do n8n, de community nodes ou da API integrada podem afetar parâmetros e credenciais. Confirme versões antes de substituir o nó.
Uma execução salva é uma evidência
Guarde o ID da execução, horário, modo de disparo, dados de entrada e mensagem completa. Ao testar novamente, use uma cópia do workflow ou dados anonimizados em ambiente isolado. Executar produção manualmente pode repetir operações que já foram concluídas antes da falha.
n8n webhook não funciona
Um webhook envolve duas pontas: o sistema que envia a requisição e o n8n que a recebe. Verifique o histórico de entrega na origem e o histórico de execuções no n8n. Se não existe tentativa no remetente, o problema está antes do n8n; se existe uma resposta HTTP, ela ajuda a localizar a camada afetada.
| Verificação | Falha comum | Como interpretar |
|---|---|---|
| URL de teste x produção | A integração permanente foi cadastrada com a URL temporária de teste. | A URL de teste só escuta durante o teste; use a URL de produção para operação contínua. |
| Workflow publicado | O fluxo foi salvo, mas não está publicado ou ativo para receber eventos. | Confirme o estado compatível com a versão do n8n e faça um evento controlado. |
| URL pública | O n8n gera endereço interno, HTTP ou domínio incorreto atrás do proxy. | Revise URL pública, cabeçalhos encaminhados e configuração do proxy reverso. |
| HTTPS, DNS e firewall | Certificado inválido, domínio errado ou porta bloqueada. | Teste resolução, cadeia TLS e acesso externo até o proxy e o container. |
| Método e autenticação | Origem envia GET, mas o nó espera POST, ou o token não corresponde. | Compare método, caminho, headers e mecanismo de autenticação dos dois lados. |
| Resposta e timeout | O fluxo demora e a origem encerra a conexão ou tenta de novo. | Defina a estratégia de resposta adequada e processe tarefas longas sem manter a origem esperando. |
Em instalações com proxy reverso, a documentação do n8n orienta configurar a URL pública do webhook e encaminhar os cabeçalhos esperados. Evite corrigir o sintoma cadastrando IP interno ou desativando HTTPS: isso cria uma integração frágil e pode expor dados e credenciais.
Por que o n8n executa o mesmo workflow duas vezes
Duas execuções no n8n nem sempre significam que o n8n criou o evento duas vezes. Muitos provedores reenviam um webhook quando não recebem confirmação dentro do prazo ou quando a conexão cai antes da resposta. A primeira execução pode ter realizado a ação e falhado antes de confirmar o recebimento.
- O provedor enviou o mesmo evento novamente após timeout ou resposta 5xx.
- Dois gatilhos, dois workflows ou ambientes diferentes estão inscritos no mesmo evento.
- Mais de uma instância recebe a mesma integração sem uma topologia distribuída corretamente configurada.
- O fluxo não verifica um ID único antes de enviar mensagem, criar cobrança ou atualizar registro.
- Uma retentativa recomeça o processo depois de uma ação externa concluída, mas antes de seu registro local.
- Eventos antigos ficaram acumulados e foram entregues após a recuperação da origem ou da fila.
- Queue mode, workers ou instâncias principais foram configurados de maneira divergente.
Idempotência protege ações irreversíveis
Antes de executar a ação principal, registre o identificador único fornecido pela origem — por exemplo, ID do evento, pedido ou mensagem — em armazenamento persistente. Se ele já foi processado, encerre o fluxo de forma controlada. A implementação deve considerar concorrência: apenas consultar e depois gravar pode permitir que duas execuções simultâneas passem pela mesma verificação.
n8n fora do ar ou reiniciando no Docker
Quando o n8n fica fora do ar, confirme primeiro se a VPS responde e se o container está em execução. Uma política automática de restart pode esconder a falha: o serviço aparece por alguns segundos, encerra e volta a subir sem resolver a causa.
Memória insuficiente
OOM, exit code e reinícios durante execuções pesadas indicam pressão de RAM. Arquivos grandes, muitos itens e alta concorrência ampliam o consumo.
Banco indisponível
Falha de DNS, senha, conexão, migration ou limite do PostgreSQL pode impedir a inicialização e o registro de execuções.
Redis indisponível
Em queue mode, a perda do broker impede o despacho normal dos jobs e pode deixar workers ociosos ou reconectando.
Variáveis incorretas
Nomes antigos, URLs divergentes, chave de criptografia diferente e configuração incompleta podem quebrar startup, credenciais ou comunicação interna.
Disco cheio
Banco, logs, arquivos binários, imagens Docker e execuções antigas podem ocupar o filesystem e interromper gravações.
Atualização incompatível
Mudança de versão sem revisar breaking changes, nodes e migrations pode impedir o start ou alterar o comportamento dos workflows.
Permissões de volume
Usuário incorreto, mount somente leitura ou proprietário divergente pode impedir o acesso ao diretório persistente.
Healthcheck inadequado
Um teste agressivo ou apontado para porta errada pode marcar o container como não saudável antes de ele terminar a inicialização.
Compare logs do n8n, eventos do Docker e métricas da VPS no mesmo horário. O primeiro erro antes do encerramento é mais útil que as mensagens de inicialização geradas depois. Em ambientes Docker, confira também uptime, contagem de reinícios, exit code, volumes e limites aplicados ao container.
Problemas no n8n queue mode
No n8n queue mode, a instância principal recebe gatilhos e coloca as execuções em uma fila no Redis. Os workers retiram esses jobs, executam os workflows e usam o banco para os dados persistentes. Essa arquitetura distribui carga, mas adiciona dependências e pontos de configuração.
| Sintoma | Hipóteses | Evidências necessárias |
|---|---|---|
| Execuções aguardando | Workers parados, Redis inacessível, concorrência baixa ou backlog maior que a capacidade. | Tamanho da fila, workers online, logs e taxa de entrada e conclusão. |
| Worker falha ao iniciar | Banco, Redis, variáveis ou chave de criptografia divergentes. | Configuração efetiva e versão de cada componente, sem expor segredos. |
| Timeouts frequentes | Workflow lento, API externa, limite de execução ou worker saturado. | Duração por nó, recursos, latência externa e limites configurados. |
| Banco sobrecarregado | Workers e concorrência acima da capacidade de conexões e I/O. | Conexões ativas, espera, queries, CPU e I/O do PostgreSQL. |
| Execução presa | Worker encerrado, dependência bloqueada ou estado inconsistente após falha. | Status no n8n, job no Redis, log do worker e último nó registrado. |
| Comportamento duplicado | Topologia com múltiplas instâncias principais sem configuração suportada ou gatilhos repetidos. | Mapa de containers, papéis, versões, webhooks e IDs dos eventos. |
Todos os componentes precisam usar versões compatíveis e a mesma chave de criptografia para acessar credenciais. A documentação recomenda PostgreSQL para queue mode e não oferece suporte ao SQLite nessa arquitetura distribuída. Aumentar workers sem medir o banco pode apenas transferir o gargalo para o PostgreSQL.
Falhas no PostgreSQL do n8n
Workflows, credenciais criptografadas, usuários e execuções dependem do banco. Por isso, um problema no n8n PostgreSQL pode afetar toda a instância mesmo quando o editor abre ou o container permanece ativo.
- Credenciais, hostname, porta, database ou schema diferentes dos configurados no servidor.
- Containers em redes distintas ou hostname interno que não resolve.
- Migrations incompletas ou incompatibilidade entre banco e versão do n8n após update.
- Latência alta e consultas lentas aumentando a duração das execuções.
- Limite de conexões esgotado por concorrência, workers ou outros sistemas no mesmo banco.
- Disco cheio, I/O elevado ou falta de espaço para operações internas e backups.
- Backup inexistente, incompleto ou nunca restaurado em ambiente de teste.
- Corrupção ou versão incompatível, que exige análise do PostgreSQL antes de qualquer reparo.
Não recrie o banco como primeira tentativa. Confirme conectividade, logs, capacidade, versão e backups. Preserve também a chave de criptografia do n8n: um banco restaurado sem a chave correta mantém os registros, mas as credenciais armazenadas não podem ser lidas normalmente pela instância.
Erros ao integrar APIs no n8n
O código HTTP não informa sozinho toda a causa, mas define onde começar. Registre status, corpo da resposta, headers relevantes, método e URL sem publicar tokens ou dados pessoais.
| Código | Significado prático | O que revisar |
|---|---|---|
| 400 | A API rejeitou a requisição. | JSON, campos obrigatórios, tipos, formato e mensagem de validação. |
| 401 | Autenticação ausente, inválida ou expirada. | Token, header, escopo, ambiente e renovação da credencial. |
| 403 | A identidade foi reconhecida, mas não tem permissão. | Papéis, escopos, políticas, IP permitido e acesso ao recurso. |
| 404 | Endpoint ou recurso não foi encontrado. | URL, versão da API, ID, ambiente e método usado. |
| 408 | A requisição expirou antes de terminar. | Latência, tamanho, processamento, rede e timeout dos dois lados. |
| 429 | O limite de requisições foi atingido. | Headers de limite, intervalo, concorrência e backoff controlado. |
| 500 | O serviço remoto encontrou uma falha interna. | Corpo da resposta, status do fornecedor e retry com limite e idempotência. |
Problemas com IA dentro do n8n
Nós de IA adicionam dependências que não existem em uma integração determinística. Uma execução tecnicamente bem-sucedida ainda pode produzir uma resposta inadequada para o passo seguinte. Por isso, valide conteúdo e estrutura antes de acionar ferramentas, enviar mensagens ou alterar dados.
Modelo indisponível
O provedor pode apresentar instabilidade, remover um modelo ou restringi-lo por região e conta. Registre a resposta e defina uma política de fallback consciente.
Limite de tokens
Prompt, histórico e documentos podem exceder a janela aceita. Controle tamanho, faça divisão e não envie contexto desnecessário.
Saída malformada
Texto que deveria ser JSON pode vir inválido ou fora do schema. Use saída estruturada quando disponível e valide antes do próximo nó.
Custo inesperado
Loops, retries, muitos itens e modelos caros podem multiplicar consumo. Monitore volume, tokens, frequência e custo por fluxo.
Credencial ou quota
Chave inválida, saldo, limite e permissão do modelo geram erros diferentes. Consulte o status retornado pelo provedor.
Timeout
Arquivos grandes, modelos lentos ou alta concorrência podem exceder limites do nó, proxy ou workflow.
Prompt inconsistente
Entradas ambíguas e sem exemplos aumentam variação. Defina objetivo, contexto, restrições e formato esperado.
Ausência de validação
Nunca presuma que a resposta é correta ou segura. Valide campos, regras de negócio e ações sensíveis antes de executá-las.
Checklist de diagnóstico rápido do n8n
Antes de alterar produção ou solicitar suporte n8n, reúna estas informações:
- 1Abra a execução afetada e registre ID, horário, gatilho e primeiro nó com erro.
- 2Salve a mensagem completa, o status HTTP e entradas e saídas relevantes sem expor segredos.
- 3Confirme se credenciais estão válidas e pertencem ao ambiente correto.
- 4Consulte logs do n8n, workers, Docker e proxy no horário exato da falha.
- 5Verifique containers, uptime, reinícios, healthchecks, versão e exit codes.
- 6Teste disponibilidade, conexões, espaço e logs do PostgreSQL.
- 7Em queue mode, valide Redis, workers, fila, concorrência e configuração compartilhada.
- 8Meça CPU, RAM, swap, disco, inodes e I/O da VPS.
- 9Confirme DNS, SSL, firewall, proxy e URL pública de webhooks.
- 10Liste mudanças recentes em workflows, credenciais, APIs, imagens e variáveis.
- 11Reproduza com dados anonimizados e sem ações irreversíveis em um ambiente isolado.
- 12Garanta um backup restaurável antes de atualizar, migrar ou remover volumes e banco.
Boas práticas para n8n em produção
Trate erros
Crie fluxos de erro e alertas com contexto suficiente para agir, sem incluir senhas, tokens ou dados sensíveis.
Controle retries
Defina quais erros podem ser repetidos, com limite, intervalo e backoff. Não repita indiscriminadamente erros 4xx.
Implemente idempotência
Proteja cobranças, mensagens e alterações contra webhooks duplicados, concorrência e retomadas.
Mantenha logs úteis
Registre IDs de correlação, serviço, etapa e resultado para relacionar eventos entre n8n, API e aplicação.
Faça backup testado
Proteja PostgreSQL, chave de criptografia e configuração persistente. Uma cópia só é confiável após teste de restauração.
Proteja credenciais
Use o cofre do n8n e secrets da plataforma, limite acessos e nunca grave tokens em nós, logs ou repositórios.
Separe ambientes
Produção e desenvolvimento devem usar bancos, credenciais, webhooks e integrações independentes.
Controle versões
Exporte e versione workflows conforme a política da empresa; recursos nativos de source control dependem do plano.
Monitore
Acompanhe disponibilidade, falhas, filas, duração, reinícios, recursos, banco, Redis, certificados e integrações críticas.
Atualize com plano
Leia release notes, fixe versões, faça backup e teste workflows e migrations antes de promover uma atualização.
Quando contratar um especialista n8n
Procure um especialista n8n quando a falha afeta produção, pagamentos, atendimento, mensagens, dados pessoais ou processos sem alternativa manual. Também é recomendável pedir apoio quando há execuções duplicadas com impacto financeiro, fila crescente, banco instável, atualização sem rollback ou ausência de backup confiável.
Alterações feitas por tentativa podem aumentar a parada, repetir ações ou eliminar evidências. Uma consultoria n8n deve analisar workflow e infraestrutura em conjunto: corrigir a expressão não resolve falta de memória, e aumentar a VPS não corrige um retry sem idempotência.
A Jupiter TI atua na criação e correção de workflows, análise de execuções, integrações com APIs, WhatsApp e agentes de IA, instalação n8n self-hosted, Docker, PostgreSQL, Redis, queue mode, migração, backup, monitoramento e suporte remoto para empresas em todo o Brasil.
Também oferecemos automação de processos, integrações com WhatsApp, agentes de IA, servidores Linux e diagnóstico de infraestrutura. A solução adequada depende da versão, dos logs, da arquitetura e do risco operacional.
Fontes técnicas para aprofundar o diagnóstico
Este conteúdo foi revisado em 31 de julho de 2026 com base na documentação oficial. Comportamentos, variáveis e recursos podem mudar entre versões e planos; consulte a documentação correspondente à instalação em uso.
Perguntas frequentes
Por que o n8n não executa um workflow?
Verifique se o workflow está publicado ou ativo quando depende de um gatilho de produção, se as credenciais continuam válidas e se o gatilho realmente recebeu o evento. Depois, consulte a execução e identifique o primeiro nó que falhou, comparando entrada, saída e mensagem completa do erro.
Por que o webhook do n8n não funciona?
As causas frequentes são uso da URL de teste fora da janela de teste, workflow de produção inativo, método HTTP ou caminho incorreto, domínio público mal configurado, proxy reverso, HTTPS inválido, firewall, autenticação ou timeout no processamento.
Por que um workflow do n8n executa duas vezes?
Pode haver eventos duplicados na origem, retry do remetente após timeout, gatilhos sobrepostos ou mais de uma instância processando a mesma integração. Use um identificador único do evento e uma estratégia de idempotência antes da ação irreversível.
O n8n queue mode precisa de Redis e PostgreSQL?
No queue mode, o Redis atua como broker da fila e os workers processam as execuções usando os dados persistidos no banco. A documentação do n8n recomenda PostgreSQL para essa arquitetura; SQLite não é suportado no queue mode distribuído.
O que fazer quando o n8n reinicia no Docker?
Consulte os logs anteriores ao reinício, o exit code e a contagem de reinícios. Verifique falta de memória, disco cheio, banco ou Redis indisponível, variáveis incorretas, permissões de volume, healthcheck e incompatibilidade após atualização.
A Jupiter TI oferece suporte para n8n self-hosted?
Sim. A Jupiter TI oferece instalação, diagnóstico e suporte remoto para n8n self-hosted, workflows, webhooks, Docker, PostgreSQL, Redis, queue mode, integrações com APIs, WhatsApp e IA, além de migração, backup e monitoramento.
Jupiter TI
Precisa de suporte n8n para uma automação em produção?
Seu workflow está falhando, repetindo mensagens ou deixando de executar? A Jupiter TI pode analisar sua automação e a infraestrutura do n8n para encontrar a causa e corrigir o problema com segurança, conforme o diagnóstico do ambiente.