- A regra de ouro do debug: comece pela execução que falhou, não saia mexendo em nó aleatório. O n8n já marca em vermelho onde quebrou.
- Nó 'solto' (a linha não encaixou na bolinha de entrada) é o erro visual nº 1 — e o mais bobo de resolver.
- Credencial expirada é a causa mais frequente de fluxo que 'funcionava e parou' sem você ter mexido em nada.
- 'Invalid JSON' e erro de mapeamento quase sempre são a mesma coisa: o nó seguinte esperava um campo que não veio com o nome certo.
- Sem tratamento de erro, uma única API fora do ar derruba a automação toda. Retry On Fail e um Error Workflow resolvem 90% disso.
1. Nó desconectado — a linha não encaixou
Você monta o fluxo, roda e um nó simplesmente não executa. Olhe a linha: se ela não travou dentro da bolinha de entrada do nó, ele está isolado e o n8n pula ele. Arraste de novo a conexão do nó anterior até encaixar com o 'clique'. Parece besteira, mas é o erro que mais consome tempo de quem está começando — porque não gera mensagem de erro, o nó só fica quieto.
2. Credencial expirada ou revogada
Token de API, chave da OpenAI, conexão do Google que pede reautenticação — quando expiram, o nó devolve erro de autenticação (401/403). Vá em Credentials, abra a credencial do serviço e clique em reconectar ou cole a chave nova. Dica: se um fluxo que rodava há semanas parou 'do nada', comece por aqui. Em 8 de 10 casos é credencial vencida, não o seu workflow.
3. Invalid JSON — dado no formato errado
Esse erro aparece quando o dado que chega a um nó não é um JSON válido: veio uma string onde se esperava objeto, faltou uma chave, ou uma API devolveu HTML de erro em vez de dados. Abra o nó que falhou, olhe a aba de INPUT e veja o que realmente entrou. Um nó Set ou Edit Fields no meio do caminho normaliza o conteúdo antes de seguir.
4. Mapeamento de campo que não bate
Você referencia {{ $json.email }} mas o campo veio como 'Email' ou 'e_mail'. O n8n não acha, devolve undefined e o próximo passo quebra. Use o painel de expressões arrastando o campo direto do INPUT em vez de digitar o nome na mão — assim o caminho vem exato, com maiúscula, minúscula e tudo. Erros de mapeamento são a causa silenciosa de metade dos fluxos que 'rodam mas não fazem nada'.
5. Testar só o cenário perfeito
Muita gente testa com um lead completo, tudo preenchido, API no ar — e manda pra produção. Aí chega um contato sem telefone, ou a API cai por 30 segundos, e o fluxo trava. Antes de ativar, rode de propósito com dados incompletos e veja o que acontece. Testar o caso ruim é o que separa uma automação que aguenta o dia a dia de uma que você vai ficar consertando toda semana.
6. Nenhum tratamento de erro — tudo para na primeira falha
Por padrão, quando um nó falha, o n8n para o workflow inteiro. Numa automação com 15 passos, o passo 4 dá erro e os 11 seguintes nem rodam. Em cada nó, aba Settings, existe 'On Error': deixe 'Stop Workflow' só nos passos críticos e use 'Continue' ou a saída de erro nos secundários, para o fluxo seguir mesmo quando algo não essencial falha.
7. Não usar Retry On Fail em chamadas de API
APIs falham por segundos o tempo todo — timeout, limite de requisições, instabilidade. Sem retry, uma falha de 2 segundos vira erro definitivo. Abra o nó, Settings > Retry On Fail, ligue, defina 3 tentativas e um tempo de espera entre elas (5 segundos para APIs comuns, 30 para serviços com rate limit). Isso sozinho elimina a maioria dos erros 'fantasma' que somem quando você roda de novo na mão.
8. Sem Error Workflow — você só descobre o erro tarde demais
Vá em Settings do workflow > Error Workflow e aponte para um fluxo que te avise quando algo falhar. Esse fluxo de erro recebe um objeto pronto: nome do workflow, nó que quebrou, mensagem do erro, ID da execução e um link direto pra ela. Ligue num Telegram ou e-mail e você fica sabendo da falha na hora — não quando o cliente reclama que nada foi enviado.
Antes de tudo: leia a execução que falhou
Existe um reflexo ruim em quem está começando: deu erro, sai mexendo em nó aleatório até 'destravar'. É o caminho mais lento. O n8n guarda o histórico de cada execução, e a que falhou aparece marcada — normalmente com o nó problemático em vermelho.
Clique nela, abra o primeiro nó que quebrou e olhe duas abas: INPUT (o que entrou) e OUTPUT (o que saiu, ou o erro). Noventa por cento dos problemas de iniciante se resolvem só comparando o que o nó esperava com o que de fato chegou. É debug de cinco minutos em vez de meia hora no escuro.
A diferença entre um erro e uma automação que 'roda mas não faz nada'
Nem todo problema no n8n grita. Alguns fluxos rodam verdinhos do começo ao fim e ainda assim não entregam o resultado — não mandaram o e-mail, não criaram o lead, não atualizaram a planilha. Esse é o caso mais traiçoeiro, porque não tem mensagem de erro pra te guiar.
Quase sempre a raiz é mapeamento: um campo referenciado com o nome errado devolve undefined, e o nó segue em frente com o campo vazio. Por isso vale o hábito de arrastar os campos do painel de INPUT em vez de digitar o caminho na mão. E, quando um fluxo 'funciona' mas não produz nada, abra o último nó e confira o OUTPUT antes de culpar a integração externa.
As três camadas de tratamento de erro que todo fluxo sério tem
Automação boa não é a que nunca falha — é a que falha sem derrubar tudo e te avisa. Pense em três camadas. A primeira é o Retry On Fail no nível do nó, que segura as falhas passageiras de API sem você nem perceber.
A segunda é o 'On Error' por nó, decidindo o que é crítico (para o fluxo) e o que é secundário (segue em frente). A terceira é o Error Workflow global, que captura tudo que escapou e te notifica com o nó, a mensagem e o link da execução. Com essas três, uma API instável vira um aviso no Telegram, não um cliente irritado no dia seguinte.
Se você está montando fluxos que rodam sozinhos 24h — um agente, um follow-up, uma cobrança — essas camadas deixam de ser luxo e viram o mínimo. É a diferença entre confiar na automação e ter que checar ela toda manhã.
Erros que aparecem mais no self-hosted
Quem roda o n8n na própria VPS herda uma categoria extra de dor: 'Connection refused', webhook que não recebe nada, gatilho de Telegram ou WhatsApp que não dispara. Aqui o problema raramente é o workflow — é infraestrutura. Endereço público com HTTPS, porta certa, serviço no ar.
Antes de reconstruir o fluxo, teste a conectividade por fora (um cURL simples até o endpoint já mostra muita coisa) e confira a página de status do serviço que você está chamando. E não esqueça do básico do self-hosted: backup e uma configuração mínima que aguente o volume. Um fluxo perfeito numa VPS mal dimensionada falha do mesmo jeito.
Perguntas frequentes
Por que meu nó no n8n não executa e não dá erro?
O que significa o erro 'Invalid JSON' no n8n?
Meu workflow parou de funcionar sozinho, o que houve?
Como impedir que uma única falha derrube a automação inteira?
Qual a forma mais rápida de achar onde o fluxo quebrou?
Leia também
O que é n8n? Guia completo para iniciantes em 2026
Entenda o que é n8n, como a ferramenta de automação funciona, quanto custa, se é difícil de aprender e como criar seu primeiro workflow sem saber programar.
Ler →
Como criar um agente de IA com n8n sem saber programar
Crie um agente de IA com n8n sem escrever código: conecte a OpenAI, dê memória de conversa ao nó AI Agent, ligue ferramentas e coloque no WhatsApp. Passo a passo em português, do zero.
Ler →
Como instalar n8n em VPS no Brasil (guia completo com custos reais)
Guia passo a passo para instalar n8n self-hosted em VPS no Brasil. Inclui custos reais em reais, comparativo de providers, configuração com Docker e HTTPS.
Ler →
Como fazer backup do n8n self-hosted e restaurar sem perder workflows
Guia prático de backup e restauração do n8n self-hosted: exportar workflows e credenciais via CLI, dump do PostgreSQL, a chave de criptografia que não pode faltar e como automatizar tudo.
Ler →
n8n self-hosted vs n8n cloud: qual vale mais a pena para o seu caso?
Compare n8n self-hosted e n8n cloud em 2026: preços, limites, facilidade de uso e quando cada opção faz sentido para iniciantes, agências e empresas.
Ler →