n8n Workflow & Code Review Agent

Run this checklist against ANY n8n workflow JSON, custom node code, or deployment configuration to catch errors before they reach production.

Quick Reference: Review Areas

Decision Tree: Review Workflow

START: What are you reviewing?
├─ Workflow JSON file (.json)
│  ├─ Run: Workflow JSON checks (Section 1)
│  ├─ Run: Connection Wiring checks (Section 2)
│  ├─ Run: Expression checks on all parameter values (Section 3)
│  ├─ Run: Error Handling checks (Section 6)
│  └─ Run: Anti-Pattern scan (Section 10)
│
├─ Custom node code (.node.ts)
│  ├─ Run: Node Type checks (Section 5)
│  ├─ Run: Credential checks if node uses credentials (Section 4)
│  ├─ Run: Error Handling checks (Section 6)
│  └─ Run: Anti-Pattern scan (Section 10)
│
├─ Credential definition (.credentials.ts)
│  └─ Run: Credential checks (Section 4)
│
├─ Code node content
│  ├─ Run: Code Node checks (Section 8)
│  └─ Run: Anti-Pattern scan (Section 10)
│
├─ Deployment config (docker-compose.yml / env vars)
│  ├─ Run: Deployment checks (Section 7)
│  └─ Run: Security checks (Section 9)
│
└─ Full project audit
   └─ Run ALL sections sequentially

1. Workflow JSON Validation

ALWAYS verify these required fields on every node in nodes[]:

ALWAYS verify the workflow root object contains:

• id (string)
• name (string)
• active (boolean)
• nodes (array)
• connections (object)

NEVER accept a workflow where two nodes share the same name — connections reference nodes by name, so duplicates break wiring.

2. Connection Wiring Validation

IConnections uses 3-level nesting:

connections[sourceNodeName][connectionType][outputIndex] = IConnection[]

ALWAYS verify:

1. Every key in connections matches a name in nodes[]
2. Every IConnection.node value matches a name in nodes[]
3. IConnection.type is a valid NodeConnectionType (usually "main")
4. IConnection.index does not exceed the destination node's input count
5. Trigger nodes (group: ['trigger']) have NO incoming connections
6. Non-trigger nodes have at least one incoming connection (unless intentionally orphaned)
7. Multi-output nodes (IF, Switch) have the correct number of output arrays

IF node pattern: connections["IF"].main MUST have exactly 2 arrays — index 0 for true, index 1 for false.

3. Expression Validation

ALWAYS verify expressions ({{ ... }}) use correct variable references:

ALWAYS verify $jmespath(object, searchString) parameter order — object FIRST, search string SECOND. This differs from the JMESPath spec.

NEVER allow $("<NodeName>") to reference a node name that does not exist in the workflow.

4. Credential Validation

ALWAYS verify ICredentialType implementations include:

ALWAYS verify authenticate.type is 'generic' — other values are not supported.

ALWAYS verify credential expressions use $credentials prefix: ={{$credentials.apiKey}}.

NEVER allow credentials to be hardcoded in node parameters — ALWAYS use credential references.

5. Node Type Validation

ALWAYS verify INodeType implementations:

ALWAYS verify execute() returns [returnData] (wrapped in outer array), NOT just returnData.

ALWAYS verify each item in the return array has a json property: { json: { ... } }.

6. Error Handling Validation

ALWAYS verify:

1. Error workflow configured — settings.errorWorkflow is set in production workflows
2. continueOnFail pattern — nodes using this.continueOnFail() include error data in output:

   returnData.push({ json: { error: error.message }, pairedItem: { item: i } });

1. Retry on transient failures — HTTP/API nodes set retryOnFail: true, maxTries >= 2, waitBetweenTries >= 1000
2. Error node exists — at least one Error Trigger workflow is available for the instance
3. `onError` setting — nodes specify behavior: 'continueErrorOutput', 'continueRegularOutput', or 'stopWorkflow'

NEVER allow a production workflow without an error workflow — silent failures are unacceptable.

7. Deployment Validation

ALWAYS verify for production deployments:

Queue mode additional requirements:

8. Code Node Validation

ALWAYS verify Code node content:

9. Security Validation

ALWAYS verify:

1. No hardcoded credentials — API keys, tokens, passwords NEVER in node parameters or Code node
2. Encryption key set — N8N_ENCRYPTION_KEY is explicitly configured (not auto-generated)
3. Task runners enabled — N8N_RUNNERS_ENABLED=true (isolates Code node execution)
4. File access restricted — N8N_RESTRICT_FILE_ACCESS_TO limits filesystem paths
5. Settings permissions — N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
6. Env access blocked — N8N_BLOCK_ENV_ACCESS_IN_NODE=true if env vars contain secrets
7. Webhook authentication — production webhooks use Basic Auth, Header Auth, or JWT
8. HTTPS enforced — N8N_PROTOCOL=https with valid TLS termination
9. Secure cookies — N8N_SECURE_COOKIE=true in HTTPS deployments

10. Anti-Pattern Detection

Scan for ALL anti-patterns listed in anti-patterns.md. Key categories:

• Expression anti-patterns: Wrong variable context, reversed JMESPath args, new Date() instead of Luxon
• Code node anti-patterns: Restricted variables, wrong return format, direct binary access
• Credential anti-patterns: Hardcoded secrets, missing test endpoint, wrong authenticate type
• Deployment anti-patterns: Missing encryption key, SQLite in production, no volume mounts
• Workflow anti-patterns: No error workflow, duplicate node names, orphan nodes

Review Report Template

After completing all applicable checks, produce a report:

## n8n Review Report

**Target**: [filename or description]
**Type**: [Workflow JSON | Custom Node | Credential | Deployment Config | Code Node]
**Date**: [date]

### Summary
- Total checks: [N]
- Passed: [N]
- Failed: [N]
- Warnings: [N]

### Critical Failures
1. [Area] — [What failed] — [Expected state] — [How to fix]

### Warnings
1. [Area] — [What to improve] — [Recommendation]

### Anti-Patterns Detected
1. [AP-XXX] — [Description] — [Location in code/config]

Reference Links

• Validation Methods (Complete Checklist)
• Review Examples (Good/Bad/Fix)
• Anti-Pattern Catalog