N8n Validation Expert

n8n Validation Expert

Guia especializado para interpretar e corrigir erros de validação n8n.

Filosofia de Validação

Valide cedo, valide frequentemente

Validação é tipicamente iterativa:

• Espere loops de feedback de validação
• Geralmente 2-3 ciclos de validação → correção
• Média: 23s pensando sobre erros, 58s consertando-os

Insight principal: Validação é um processo iterativo, não pontual!

Níveis de Severidade de Erro

1. Erros (Deve Corrigir)

Bloqueia execução do workflow - Deve ser resolvido antes da ativação

Tipos:

• missing_required - Campo obrigatório não fornecido
• invalid_value - Valor não corresponde às opções permitidas
• type_mismatch - Tipo de dado incorreto (string em vez de número)
• invalid_reference - Nó referenciado não existe
• invalid_expression - Erro de sintaxe de expressão

Exemplo:

{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required",
  "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
}

2. Avisos (Deveria Corrigir)

Não bloqueia execução - Workflow pode ser ativado mas pode ter problemas

Tipos:

• best_practice - Recomendado mas não obrigatório
• deprecated - Usando API/recurso antigo
• performance - Possível problema de performance

Exemplo:

{
  "type": "best_practice",
  "property": "errorHandling",
  "message": "Slack API can have rate limits",
  "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}

3. Sugestões (Opcional)

Legal ter - Melhorias que poderiam aprimorar o workflow

Tipos:

• optimization - Poderia ser mais eficiente
• alternative - Forma melhor de atingir o mesmo resultado

O Loop de Validação

Padrão da Telemetria

7.841 ocorrências deste padrão:

1. Configurar nó
   ↓
2. validate_node_operation (23 segundos pensando sobre erros)
   ↓
3. Ler mensagens de erro com atenção
   ↓
4. Corrigir erros
   ↓
5. validate_node_operation novamente (58 segundos consertando)
   ↓
6. Repetir até válido (geralmente 2-3 iterações)

Exemplo

// Iteração 1
let config = {
  resource: "channel",
  operation: "create"
};

const result1 = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "name"

// ⏱️  23 segundos pensando...

// Iteração 2
config.name = "general";

const result2 = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "text"

// ⏱️  58 segundos consertando...

// Iteração 3
config.text = "Hello!";

const result3 = validate_node_operation({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Valid! ✅

Isso é normal! Não se desanime com múltiplas iterações.

Perfis de Validação

Escolha o perfil certo para seu estágio:

minimal

Use quando: Verificações rápidas durante edição

Valida:

• Apenas campos obrigatórios
• Estrutura básica

Prós: Mais rápido, mais permissivo Contras: Pode perder problemas

runtime (RECOMENDADO)

Use quando: Validação pré-deployment

Valida:

• Campos obrigatórios
• Tipos de valor
• Valores permitidos
• Dependências básicas

Prós: Balanceado, pega erros reais Contras: Alguns casos extremos perdidos

Este é o perfil recomendado para a maioria dos casos de uso

ai-friendly

Use quando: Configurações geradas por IA

Valida:

• O mesmo que runtime
• Reduz falsos positivos
• Mais tolerante com problemas menores

Prós: Menos ruído para workflows IA Contras: Pode permitir algumas configs questionáveis

strict

Use quando: Deployment em produção, workflows críticos

Valida:

• Tudo
• Best practices
• Preocupações de performance
• Problemas de segurança

Prós: Máxima segurança Contras: Muitos avisos, alguns falsos positivos

Tipos de Erro Comuns

1. missing_required

O que significa: Um campo obrigatório não foi fornecido

Como corrigir:

1. Use get_node_essentials para ver campos obrigatórios
2. Adicione o campo faltante à sua configuração
3. Forneça um valor apropriado

Exemplo:

// Erro
{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required"
}

// Correção
config.channel = "#general";

2. invalid_value

O que significa: Valor não corresponde às opções permitidas

Como corrigir:

1. Verifique a mensagem de erro para valores permitidos
2. Use get_node_essentials para ver opções
3. Atualize para um valor válido

Exemplo:

// Erro
{
  "type": "invalid_value",
  "property": "operation",
  "message": "Operation must be one of: post, update, delete",
  "current": "send"
}

// Correção
config.operation = "post";  // Use operação válida

3. type_mismatch

O que significa: Tipo de dado incorreto para o campo

Como corrigir:

1. Verifique o tipo esperado na mensagem de erro
2. Converta o valor para o tipo correto

Exemplo:

// Erro
{
  "type": "type_mismatch",
  "property": "limit",
  "message": "Expected number, got string",
  "current": "100"
}

// Correção
config.limit = 100;  // Número, não string

4. invalid_expression

O que significa: Erro de sintaxe de expressão

Como corrigir:

1. Use a skill n8n Expression Syntax
2. Verifique se há {{}} faltando ou erros de digitação
3. Verifique referências de nó/campo

Exemplo:

// Erro
{
  "type": "invalid_expression",
  "property": "text",
  "message": "Invalid expression: $json.name",
  "current": "$json.name"
}

// Correção
config.text = "={{$json.name}}";  // Adicione {{}}

5. invalid_reference

O que significa: Nó referenciado não existe

Como corrigir:

1. Verifique a ortografia do nome do nó
2. Verifique se o nó existe no workflow
3. Atualize a referência para o nome correto

Exemplo:

// Erro
{
  "type": "invalid_reference",
  "property": "expression",
  "message": "Node 'HTTP Requets' does not exist",
  "current": "={{$node['HTTP Requets'].json.data}}"
}

// Correção - corrija o typo
config.expression = "={{$node['HTTP Request'].json.data}}";

Sistema de Auto-Sanitização

O que Faz

Corrige automaticamente problemas comuns de estrutura de operadores em QUALQUER atualização de workflow

Executa quando:

• n8n_create_workflow
• n8n_update_partial_workflow
• Qualquer operação de salvamento de workflow

O que Corrige

1. Operadores Binários (Dois Valores)

Operadores: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith

Correção: Remove propriedade singleValue (operadores binários comparam dois valores)

Antes:

{
  "type": "boolean",
  "operation": "equals",
  "singleValue": true  // ❌ Errado!
}

Depois (automático):

{
  "type": "boolean",
  "operation": "equals"
  // singleValue removido ✅
}

2. Operadores Unários (Um Valor)

Operadores: isEmpty, isNotEmpty, true, false

Correção: Adiciona singleValue: true (operadores unários verificam um valor)

Antes:

{
  "type": "boolean",
  "operation": "isEmpty"
  // singleValue faltando ❌
}

Depois (automático):

{
  "type": "boolean",
  "operation": "isEmpty",
  "singleValue": true  // ✅ Adicionado
}

3. Metadados IF/Switch

Correção: Adiciona metadados completos conditions.options para IF v2.2+ e Switch v3.2+

O que NÃO PODE Corrigir

1. Conexões Quebradas

Referências a nós que não existem

Solução: Use operação cleanStaleConnections em n8n_update_partial_workflow

2. Incompatibilidades de Contagem de Branches

3 regras de Switch mas apenas 2 conexões de saída

Solução: Adicione conexões faltantes ou remova regras extras

3. Estados Corrompidos Paradoxais

API retorna dados corrompidos mas rejeita atualizações

Solução: Pode exigir intervenção manual no banco de dados

Falsos Positivos

O que São?

Avisos de validação que estão tecnicamente "errados" mas aceitáveis no seu caso de uso

Falsos Positivos Comuns

1. "Missing error handling"

Aviso: Nenhum tratamento de erro configurado

Quando aceitável:

• Workflows simples onde falhas são óbvias
• Workflows de teste/desenvolvimento
• Notificações não críticas

Quando corrigir: Workflows em produção lidando com dados importantes

2. "No retry logic"

Aviso: Nó não tenta novamente em caso de falha

Quando aceitável:

• APIs com lógica de retry própria
• Operações idempotentes
• Workflows com trigger manual

Quando corrigir: Serviços externos instáveis, automação em produção

3. "Missing rate limiting"

Aviso: Nenhum rate limiting para chamadas de API

Quando aceitável:

• APIs internas sem limites
• Workflows de baixo volume
• APIs com rate limiting no servidor

Quando corrigir: APIs públicas, workflows de alto volume

4. "Unbounded query"

Aviso: SELECT sem LIMIT

Quando aceitável:

• Conjuntos de dados pequenos conhecidos
• Queries de agregação
• Desenvolvimento/teste

Quando corrigir: Queries em produção em tabelas grandes

Reduzindo Falsos Positivos

Use perfil ai-friendly:

validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {...},
  profile: "ai-friendly"  // Menos falsos positivos
})

Estrutura de Resultado de Validação

Resposta Completa

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "channel",
      "message": "Channel name is required",
      "fix": "Provide a channel name (lowercase, no spaces)"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API can have rate limits",
      "suggestion": "Add onError: 'continueRegularOutput'"
    }
  ],
  "suggestions": [
    {
      "type": "optimization",
      "message": "Consider using batch operations for multiple messages"
    }
  ],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1,
    "suggestionCount": 1
  }
}

Como Ler

1. Verifique campo valid

if (result.valid) {
  // ✅ Configuração é válida
} else {
  // ❌ Tem erros - deve corrigir antes do deployment
}

2. Corrija erros primeiro

result.errors.forEach(error => {
  console.log(`Error in ${error.property}: ${error.message}`);
  console.log(`Fix: ${error.fix}`);
});

3. Revise avisos

result.warnings.forEach(warning => {
  console.log(`Warning: ${warning.message}`);
  console.log(`Suggestion: ${warning.suggestion}`);
  // Decida se precisa resolver isso
});

4. Considere sugestões

// Melhorias opcionais
// Não obrigatórias mas podem aprimorar o workflow

Validação de Workflow

validate_workflow (Estrutura)

Valida workflow inteiro, não apenas nós individuais

Verifica:

1. Configurações de nó - Cada nó válido
2. Conexões - Sem referências quebradas
3. Expressões - Sintaxe e referências válidas
4. Fluxo - Estrutura lógica do workflow

Exemplo:

validate_workflow({
  workflow: {
    nodes: [...],
    connections: {...}
  },
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

Erros Comuns de Workflow

1. Conexões Quebradas

{
  "error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}

Correção: Remova conexão obsoleta ou crie nó faltante

2. Dependências Circulares

{
  "error": "Circular dependency detected: Node A → Node B → Node A"
}

Correção: Reestruture workflow para remover loop

3. Múltiplos Nós de Início

{
  "warning": "Multiple trigger nodes found - only one will execute"
}

Correção: Remova triggers extras ou divida em workflows separados

4. Nós Desconectados

{
  "warning": "Node 'Transform' is not connected to workflow flow"
}

Correção: Conecte nó ou remova se não usado

Estratégias de Recuperação

Estratégia 1: Comece do Zero

Quando: Configuração está severamente quebrada

Passos:

1. Anote campos obrigatórios de get_node_essentials
2. Crie configuração válida mínima
3. Adicione features incrementalmente
4. Valide após cada adição

Estratégia 2: Busca Binária

Quando: Workflow valida mas executa incorretamente

Passos:

1. Remova metade dos nós
2. Valide e teste
3. Se funciona: problema está nos nós removidos
4. Se falha: problema está nos nós restantes
5. Repita até isolar o problema

Estratégia 3: Limpar Conexões Obsoletas

Quando: Erros "Node not found"

Passos:

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{
    type: "cleanStaleConnections"
  }]
})

Estratégia 4: Use Auto-fix

Quando: Erros de estrutura de operador

Passos:

n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false  // Visualize primeiro
})

// Revise correções, depois aplique
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

Melhores Práticas

✅ Faça

• Valide após cada mudança significativa
• Leia mensagens de erro completamente
• Corrija erros iterativamente (um por vez)
• Use perfil runtime para pré-deployment
• Verifique campo valid antes de assumir sucesso
• Confie em auto-sanitização para problemas de operador
• Use get_node_essentials quando incerto sobre requisitos
• Documente falsos positivos que aceita

❌ Não Faça

• Pule validação antes da ativação
• Tente corrigir todos os erros de uma vez
• Ignore mensagens de erro
• Use perfil strict durante desenvolvimento (muito ruído)
• Assuma que validação passou (sempre verifique resultado)
• Corrija manualmente problemas de auto-sanitização
• Deployment com erros não resolvidos
• Ignore todos os avisos (alguns são importantes!)

Guias Detalhados

Para catálogos de erro abrangentes e exemplos de falsos positivos:

• ERROR_CATALOG.md - Lista completa de tipos de erro com exemplos
• FALSE_POSITIVES.md - Quando avisos são aceitáveis

Resumo

Pontos-chave:

1. Validação é iterativa (média 2-3 ciclos, 23s + 58s)
2. Erros devem ser corrigidos, avisos são opcionais
3. Auto-sanitização corrige estruturas de operador automaticamente
4. Use perfil runtime para validação balanceada
5. Falsos positivos existem - aprenda a reconhecê-los
6. Leia mensagens de erro - elas contêm orientação de correção

Processo de Validação:

1. Valide → Leia erros → Corrija → Valide novamente
2. Repita até válido (geralmente 2-3 iterações)
3. Revise avisos e decida se aceitável
4. Deployment com confiança

Skills Relacionadas:

• n8n MCP Tools Expert - Use ferramentas de validação corretamente
• n8n Expression Syntax - Corrija erros de expressão
• n8n Node Configuration - Entenda campos obrigatórios