Skip to main content

​
Overview

Validate a workflow by ID to catch errors before execution. Checks node configurations, connections, expressions, and overall workflow structure.
Always validate workflows before deployment to catch configuration errors, broken connections, and invalid expressions.

​
Endpoint

POST /workflows/:id/validate

​
Request Parameters

​
id
string
required
Workflow ID to validateExample: "wf_abc123"
​
options
object
Validation options

​
Response

​
success
boolean
Operation success status
​
data
object
Validation result

​
Validation Error Types

​
Node Configuration Errors

​
MISSING_REQUIRED_PARAMETER
error
Cause: Required node parameter not setExample: HTTP Request node missing url parameterResolution: Provide the required parameter value
​
INVALID_PARAMETER_TYPE
error
Cause: Parameter value has wrong data typeExample: Numeric field contains string valueResolution: Correct the parameter type
​
INVALID_ENUM_VALUE
error
Cause: Parameter value not in allowed optionsExample: HTTP method set to “PATCH” when only GET/POST allowedResolution: Use an allowed value

​
Connection Errors

​
ORPHANED_NODE
error
Cause: Node not connected to workflow flowResolution: Connect node or remove it
​
INVALID_CONNECTION_REFERENCE
error
Cause: Connection references non-existent nodeResolution: Use cleanStaleConnections operation
​
MISSING_TRIGGER
error
Cause: Workflow has no trigger nodeResolution: Add a trigger (Webhook, Schedule, Manual, etc.)

​
Expression Errors

​
INVALID_EXPRESSION_SYNTAX
error
Cause: Malformed n8n expressionExample: {{{ $json.field }}} (too many braces)Resolution: Fix expression syntax
​
MISSING_EXPRESSION_PREFIX
warning
Cause: Expression missing = prefixExample: {{ $json.value }} should be ={{ $json.value }}Resolution: Auto-fixed by n8n_autofix_workflow tool
​
INVALID_NODE_REFERENCE
error
Cause: Expression references non-existent nodeExample: ={{ $node['Missing Node'].json.value }}Resolution: Correct node name or remove reference

​
Examples

curl -X POST "https://n8n.example.com/api/v1/workflows/wf_abc123/validate" \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}'

​
Response Examples

{
  "success": true,
  "data": {
    "valid": true,
    "workflowId": "wf_abc123",
    "workflowName": "Customer Onboarding",
    "summary": {
      "totalNodes": 8,
      "enabledNodes": 8,
      "triggerNodes": 1,
      "validConnections": 7,
      "invalidConnections": 0,
      "expressionsValidated": 12,
      "errorCount": 0,
      "warningCount": 0
    },
    "errors": [],
    "warnings": [],
    "suggestions": [
      "Consider adding error handling with continueOnFail",
      "Add notes to complex nodes for documentation"
    ]
  }
}

​
Validation Profiles

Use Case: Quick checks during developmentValidates:
  • Required parameters only
  • Basic structure
Skips:
  • Optional parameters
  • Warnings
  • Suggestions
{"options": {"profile": "minimal"}}

​
Workflow Validation Checklist

1

Structure

✅ At least one trigger node ✅ All nodes connected (no orphans) ✅ Valid connection structure ✅ No circular dependencies
2

Nodes

✅ All required parameters set ✅ Valid parameter types ✅ Credentials configured ✅ Node versions supported
3

Expressions

✅ Valid {{ }} syntax ✅ Proper = prefix ✅ Valid node references ✅ Correct function calls
4

Connections

✅ No stale connections ✅ Proper branch routing (IF/Switch) ✅ Valid input/output indices ✅ All nodes reachable from trigger

​
Integration with Auto-Fix

Many validation errors can be automatically fixed with the n8n_autofix_workflow tool:
# 1. Validate workflow
n8n_validate_workflow({id: "wf_abc123"})

# 2. If errors found, preview auto-fixes
n8n_autofix_workflow({id: "wf_abc123", applyFixes: false})

# 3. Apply fixes
n8n_autofix_workflow({id: "wf_abc123", applyFixes: true})

# 4. Validate again
n8n_validate_workflow({id: "wf_abc123"})

​
Best Practices

Validation Workflow:
  1. During Development: Use minimal profile for fast iterations
  2. Before Testing: Use runtime profile to catch errors
  3. Before Production: Use strict profile for comprehensive checks
  4. After Auto-Fix: Re-validate to confirm fixes
  5. Periodic Audits: Validate all workflows monthly
Common Mistakes:
  • Skipping validation before deployment
  • Ignoring warnings (they often indicate real issues)
  • Not re-validating after updates
  • Disabling expression validation (catches many runtime errors)
Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Build docs developers (and LLMs) love

Get started for freeTalk to us