This page covers the critical item flow mental model. See also: n8n Overview, AI Agents, Self-Hosting.
Item Flow — The Critical Mental Model
The number of items entering a node determines how many times it executes. 3 items in = the next node runs 3 times. This is the single most important concept in n8n.
Split Out / Aggregate / Loop
1 item with [A, B, C] ──> Split Out ──> 3 separate items (A, B, C)
3 separate items ──> Aggregate ──> 1 item with [A, B, C]
100 items ──> Loop (batch=10) ──> 10 batches of 10 items
| Node | Transforms | Use When |
|---|---|---|
| Split Out | 1 item with array -> N items | Process each array element independently |
| Aggregate | N items -> 1 item with array | Combine results into a single payload |
| Loop | N items -> batches of M | Rate limits, memory issues, sequential processing |
Forgetting that item count multiplies execution is the most common mistake. An AI Agent node processing 50 items = 50 separate LLM calls. Use Loop with batch size 1-5 for expensive operations.
Sub-Workflows
Reusable, modular workflow components called from parent workflows.
Structure
Parent Workflow:
Trigger → Process → Execute Sub Workflow → Continue
Sub-Workflow:
Execute Sub Workflow Trigger → [logic] → Final Node (output returned to parent)
Rules
1
Must start with Execute Sub Workflow trigger
The sub-workflow needs this specific trigger node to receive data from the parent.
2
Define input parameters manually
Use “Define using fields below” — not “auto-detect”. Explicit is reliable.
3
Must be published
Changes to sub-workflows don’t take effect in the parent until published.
4
Returns final node output
The output of the last node in the sub-workflow is returned to the parent.
When to Create Sub-Workflows
- Same logic used across multiple workflows
- Complex node chains that clutter the main workflow
- Components that need independent testing
When using an AI Agent inside a sub-workflow, set the user message source to “Define below” and map the incoming variable explicitly. Without this, the agent receives no prompt and errors silently.
Error Handling Patterns
| Pattern | How | Use When |
|---|---|---|
| Error Trigger workflow | Separate workflow on any failure | Global monitoring and alerting |
| Continue on Error | Node setting — proceed despite failure | Graceful degradation |
| Try/Catch with If | Check output, route errors to recovery | Per-node error handling |
| Retry with Loop | Wrap failing node in Loop with counter | Transient API failures |
| Human in the Loop | Pause node waits for approval | Critical decisions |
Human in the Loop (HITL)
The Pause node stops workflow execution and waits for a human to approve or reject before continuing. Use for:
- Sending emails/messages on behalf of the user
- Financial transactions
- Calendar scheduling
- Any action that’s hard to undo
Webhooks
Webhook Trigger
External service → POST https://your-n8n.com/webhook/abc123
→ Workflow processes data
→ Returns JSON response
Security Best Practices
- Validate incoming request headers (API keys, signatures)
- Check source IP if possible
- Authenticate before processing any data
- Never expose sensitive data in webhook URLs
Production Best Practices
Development Rules
- Build node-by-node. Test after each addition, not at the end.
- Pin test data (shortcut:
P) after successful API/AI calls. Saves credits. - Use absolute node references (
$('NodeName')) — they survive restructuring. - Rename nodes descriptively. “Process Email” not “HTTP Request 3”.
- Test with cheap models first (GPT-4o Mini, Gemini Flash), switch to production models last.
Architecture Rules
- Sub-workflows for reuse. Copy-paste the same nodes twice? Extract a sub-workflow.
- Separation of concerns. System message = static rules. User message = dynamic input. Tools = actions.
- Explicit over implicit. Define all fields manually. Never rely on auto-detection in production.
- Credentials in n8n. Never hardcode API keys in Code nodes or expressions.
- Version control. Export workflows as JSON. Track changes in Git.
Reliability Rules
- Error workflows for monitoring. Dedicated error-handling workflow that sends alerts.
- Rate limit protection. Loop nodes with small batch sizes for API-heavy workflows.
- Log agent actions. Track tool calls, token usage, and outcomes.
- Human in the loop for irreversible actions. Pause before sending, deleting, paying.
- Test edge cases. Empty inputs, missing fields, API timeouts, malformed data.