Troubleshooting

Este guia apresenta soluções para problemas comuns encontrados ao usar o n8n, incluindo erros de execução, problemas de conectividade, configurações incorretas e outras questões que podem afetar o funcionamento dos workflows.

Problemas de Execução

Workflow não executa

Sintomas:

Workflow não inicia
Trigger não responde
Execução fica pendente

Soluções:

Verificar Trigger

# Verificar se o trigger está ativo
# Confirme se há dados de entrada
# Teste com dados de exemplo

Verificar Conexões

// Teste de conectividade básica
{
  "test": "conexao",
  "timestamp": "{{$now}}",
  "status": "ativo"
}

Verificar Logs

# Acessar logs do n8n
n8n logs --level debug

# Verificar logs específicos
n8n logs --level error

Erro de Autenticação

Sintomas:

Erro 401/403
Credenciais inválidas
Token expirado

Soluções:

Renovar Credenciais

// Verificar validade do token
{
  "token": "{{$credentials.apiKey}}",
  "validade": "{{$json.expires_at}}",
  "status": "ativo"
}

Verificar Permissões

Confirme se a API key tem permissões adequadas
Verifique se o escopo está correto
Teste com credenciais de teste

Configurar OAuth

// Configuração OAuth básica
{
  "client_id": "seu_client_id",
  "client_secret": "SEU_CLIENT_SECRET_AQUI",
  "redirect_uri": "https://seu-dominio.com/callback"
}

Problemas de Conectividade

API não responde

Sintomas:

Timeout de requisições
Erro de conexão
Resposta lenta

Soluções:

Verificar URL e Endpoint

// Teste de conectividade
{
  "url": "{{$json.api_url}}",
  "method": "GET",
  "timeout": 30000,
  "retry": 3
}

Configurar Timeout

// Configuração de timeout
{
  "timeout": 60000,
  "retry_attempts": 3,
  "retry_delay": 1000
}

Verificar Rate Limits

Implemente delays entre requisições
Use paginação quando necessário
Monitore limites da API

Problemas de Webhook

Sintomas:

Webhook não recebe dados
URL inválida
Erro de SSL

Soluções:

Verificar URL do Webhook

// Configuração de webhook
{
  "url": "https://seu-dominio.com/webhook",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  }
}

Configurar SSL

Use HTTPS para webhooks
Configure certificados válidos
Teste com ferramentas online

Verificar Firewall

Libere portas necessárias
Configure regras de firewall
Teste conectividade externa

Problemas de Dados

Dados incorretos

Sintomas:

Valores inesperados
Formato incorreto
Dados faltantes

Soluções:

Validar Dados de Entrada

// Função de validação
function validarDados(dados) {
  if (!dados || typeof dados !== 'object') {
    throw new Error('Dados inválidos');
  }
  return dados;
}

Verificar Mapeamento

// Mapeamento seguro
{
  "campo_original": "{{$json.campo}}",
  "campo_processado": "{{$json.campo || 'padrão'}}",
  "validacao": "{{typeof $json.campo === 'string'}}"
}

Implementar Tratamento de Erros

// Tratamento de erro
try {
  const resultado = processarDados($input.first().json);
  return [{json: resultado}];
} catch (erro) {
  console.error('Erro no processamento:', erro);
  return [{json: {erro: erro.message}}];
}

Problemas de Performance

Sintomas:

Execução lenta
Timeout frequente
Alto uso de memória

Soluções:

Otimizar Queries

// Query otimizada
{
  "limit": 100,
  "offset": 0,
  "filters": {
    "status": "ativo",
    "data_inicio": "{{$now.minus({days: 30})}}"
  }
}

Implementar Cache

// Cache simples
const cache = new Map();

function getCachedData(key) {
  if (cache.has(key)) {
    return cache.get(key);
  }
  const data = fetchData(key);
  cache.set(key, data);
  return data;
}

Usar Processamento em Lotes

// Processamento em lotes
{
  "batch_size": 50,
  "delay_between_batches": 1000,
  "max_concurrent": 5
}

Problemas de Configuração

Variáveis de Ambiente

Sintomas:

Variáveis não encontradas
Valores incorretos
Configuração não aplicada

Soluções:

Verificar Arquivo .env

# Exemplo de .env
N8N_BASIC_AUTH_ACTIVE=true
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=SUA_SENHA_SEGURA_AQUI
N8N_HOST=0.0.0.0
N8N_PORT=5678

Validar Configuração

# Verificar variáveis
echo $N8N_HOST
echo $N8N_PORT

# Testar configuração
n8n start --dry-run

Reiniciar Serviço

# Reiniciar n8n
n8n restart

# Verificar status
n8n status

Problemas de Permissões

Sintomas:

Erro de acesso negado
Arquivos não encontrados
Permissões insuficientes

Soluções:

Corrigir Permissões de Arquivos

# Corrigir permissões
sudo chown -R $USER:$USER /path/to/n8n
sudo chmod -R 755 /path/to/n8n

# Verificar permissões
ls -la /path/to/n8n

Configurar Usuário do Sistema

# Criar usuário específico
sudo useradd -r -s /bin/false n8n

# Configurar permissões
sudo chown -R n8n:n8n /path/to/n8n

Verificar Permissões de Rede

# Verificar portas
netstat -tulpn | grep 5678

# Configurar firewall
sudo ufw allow 5678

Problemas Específicos por Node

HTTP Request Node

Problemas comuns:

Timeout de requisições
Erro de SSL
Headers incorretos

Soluções:

// Configuração robusta
{
  "url": "{{$json.api_url}}",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{$credentials.apiKey}}"
  },
  "timeout": 30000,
  "retry": {
    "attempts": 3,
    "delay": 1000
  }
}

Code Node

Problemas comuns:

Erro de sintaxe
Variáveis não definidas
Loop infinito

Soluções:

// Código seguro
try {
  const dados = $input.first().json;
  
  // Validação de entrada
  if (!dados) {
    throw new Error('Dados de entrada não encontrados');
  }
  
  // Processamento
  const resultado = processarDados(dados);
  
  return [{json: resultado}];
} catch (erro) {
  console.error('Erro no Code Node:', erro);
  return [{json: {erro: erro.message}}];
}

If Node

Problemas comuns:

Condição sempre falsa
Expressão inválida
Dados não encontrados

Soluções:

// Condição robusta
{
  "condition": "{{$json.campo && $json.campo !== '' && $json.campo !== null}}",
  "true": "Dados Válidos",
  "false": "Dados Inválidos"
}

Ferramentas de Debug

Debug Helper Node

Uso:

// Configuração do Debug Helper
{
  "debug": true,
  "log_level": "debug",
  "include_input": true,
  "include_output": true
}

Logs do Sistema

Comandos úteis:

# Ver logs em tempo real
n8n logs --follow

# Filtrar por nível
n8n logs --level error

# Ver logs de execução específica
n8n logs --execution-id 123

Monitoramento

Métricas importantes:

// Métricas de performance
{
  "tempo_execucao": "{{$execution.time}}",
  "memoria_uso": "{{$execution.memory}}",
  "nodes_executados": "{{$execution.nodes}}",
  "status": "{{$execution.status}}"
}

Próximos Passos

Analisar Logs - Análise detalhada de logs
Visualizar Execuções - Monitoramento de execuções
Configurar Alertas - Sistema de notificações
Debug Helper - Node para debugging
Expressões n8n - Usar expressões para debug

Problemas de Execução​

Workflow não executa​

Erro de Autenticação​

Problemas de Conectividade​

API não responde​

Problemas de Webhook​

Problemas de Dados​

Dados incorretos​

Problemas de Performance​

Problemas de Configuração​

Variáveis de Ambiente​

Problemas de Permissões​

Problemas Específicos por Node​

HTTP Request Node​

Code Node​

If Node​

Ferramentas de Debug​

Debug Helper Node​

Logs do Sistema​

Monitoramento​

Próximos Passos​

Problemas de Execução

Workflow não executa

Erro de Autenticação

Problemas de Conectividade

API não responde

Problemas de Webhook

Problemas de Dados

Dados incorretos

Problemas de Performance

Problemas de Configuração

Variáveis de Ambiente

Problemas de Permissões

Problemas Específicos por Node

HTTP Request Node

Code Node

If Node

Ferramentas de Debug

Debug Helper Node

Logs do Sistema

Monitoramento

Próximos Passos