The n8n Compendium — Volume H: Practice and Reference

Two worked projects end to end, a recipes cookbook, a troubleshooting encyclopedia, and the mega-glossary.

A Signal Through field guide. Independent, plain-English documentation; not affiliated with or endorsed by n8n GmbH. Approximately 25621 words.

In this volume:

• Worked Project 1: The Lead Machine (Classic Automation End to End)
• Worked Project 2: The Support Copilot (AI Agent End to End)
• The Recipes Cookbook
• The Troubleshooting Encyclopedia
• Mega-Glossary and the Resource Shelf

Worked Project 1: The Lead Machine (Classic Automation End to End)

This is a full build, click by click, of a system you can put into production the same afternoon: a lead-intake pipeline that collects form submissions, enriches each one against an external API, removes duplicates, routes leads by value into your CRM and Slack, asks a human before it acts on the biggest ones, sends a daily digest, and quietly pages someone when anything breaks. It is deliberately AI-free. Every node here is classic, deterministic automation — the kind that runs the same way a million times.

The point of the chapter is consolidation, not novelty. Nothing below is a new concept; every step names the chapter that taught it, so the moment a step feels shaky you know exactly which page to reread. If you have worked through Volumes B through E, you already own every skill this project needs. What you may not yet own is the experience of assembling them into one thing that stays up. That is what you build here.

What You Are Building

The Lead Machine is three workflows, not one giant one. Splitting responsibilities is the tidiness discipline from Chapter 10 (Test, Fix, Activate, and Keep It Tidy): one trigger per workflow, one job per workflow. The three never call each other directly — they cooperate through a shared data table, which keeps each one simple enough to reason about on its own.

The intake workflow does most of the work. Its shape, stage by stage, with the chapter each stage draws on:

The screenshots-in-prose below use HubSpot as the CRM, but every CRM node in the catalog — Pipedrive, Salesforce, Zoho, and the rest (Chapter 12) — presents the same create-or-update mapping form. Substitute yours freely; only the node name and a couple of field labels change.

Groundwork Before the First Node

Three pieces of setup, all from Volume C.

Credentials (Chapter 11). You need three: a Slack credential that can post to your sales and alerts channels; a credential for your CRM; and an API key for an enrichment service — any provider that takes an email address and returns company details. Most enrichment APIs authenticate with a key in a request header, so create a generic Header Auth credential for that one rather than hunting for a dedicated node (generic credential types were Chapter 13's territory).

The data table (Chapter 20). A data table is n8n's built-in, spreadsheet-like store — remembered state that survives between executions, which is precisely what deduplication requires. From your project's home, open the Data tables area and create a table named leads with these columns:

Watch out: A data table is operational memory, not your database of record. It carries row and size limits and has no backup story of its own (Chapter 20 spells out the boundaries). The CRM stays the source of truth for lead data; the table exists only so the workflow can remember what it has already seen. Never let it drift into being the thing you would cry about losing.

Empty shells. Create all three workflows now, named exactly as in the blueprint, each with nothing on the canvas yet. You will not wire the error handler until the end, but naming things before you need them costs nothing and stops you from inventing names under pressure later.

Stage 1: Intake — the n8n Form

Open Lead Machine — Intake. Click the + on the empty canvas, search for "form", and choose On form submission. This is the n8n Form Trigger from Chapter 7 — n8n hosts the form page for you, so there is zero website work to do.

Configure it:

• Form Title: Talk to us
• Form Description: Tell us what you want to automate and we'll be in touch.
• Form Elements, in this order:
  1. Your name — Field Type Text, Required on
  2. Work email — Field Type Email, Required on
  3. Company — Field Type Text, Required off
  4. What do you need? — Field Type Textarea, Required off

The trigger panel shows two URLs, exactly as Chapter 14 described for webhooks: a Test URL that listens only while you are actively testing in the editor, and a Production URL that answers only once the workflow is activated. Click Execute step, open the Test URL in a second browser tab, and submit the form with your own details. Back in the editor, the trigger's output shows one item whose JSON carries your answers keyed by field label — Your name, Work email, and so on — plus a submittedAt timestamp. That single item is the raw material for everything downstream (Chapter 16 is the deep treatment of items).

Tip: Pin this output now — click the pin icon on the trigger's output panel. Pinned data (Chapter 10) replays that one submission every time you test a downstream node, so you never refill the form while building. Set a reminder to unpin before you activate; pinned data in a live workflow is a classic self-inflicted bug.

If your leads come from an existing website form rather than n8n's hosted one, swap this trigger for a Webhook node (POST, a path like lead-intake, respond Immediately) and point the website at it. Everything from Stage 2 onward is byte-for-byte identical. Chapter 14 covers that swap in full.

If this failed: a 404 on the Test URL means the workflow was not listening — you must click Execute step first, and the test window closes after a single submission. A form that loads but errors on submit almost always means a downstream node threw; open the execution log (Chapter 21) to see which one.

Canvas checkpoint: one node, On form submission, holding one pinned item.

Stage 2: Normalize the Lead

Raw form output has label-shaped keys full of spaces, a mixed-case email, and no defaults for the optional fields. Clean all of that up immediately with an Edit Fields (Set) node — the workhorse of Chapter 18. Add it after the trigger and rename it Normalize Lead. (Renaming every node as you add it is the Chapter 8 hygiene habit; do it throughout this build so the expressions you write later read like sentences.)

Set Mode to Manual Mapping, turn Keep Only Set Fields on, and add:

Two Chapter 17 details are doing quiet work here. Bracket notation — $json['Work email'] — is required because the key contains a space, which dot notation cannot express. And $now is n8n's built-in current-moment object, serialized to a standard timestamp string with .toISO(). Lowercasing and trimming the email is not cosmetic: it is the thing that makes deduplication reliable two stages from now, because Chris@Example.com and chris@example.com have to collapse into the same lead or the whole dedupe scheme leaks.

Run Execute step and confirm the output is one item with exactly five clean fields and nothing else.

Canvas checkpoint: On form submission → Normalize Lead.

Stage 3: Enrich via HTTP Request

Now ask an enrichment API who this person is. Add an HTTP Request node (Chapter 13), rename it Enrich Lead, and configure:

• Method: GET
• URL: your provider's person- or email-lookup endpoint
• Authentication: Generic Credential Type → Header Auth → the credential you made in the groundwork
• Send Query Parameters: on; add one parameter — Name email, Value {{ $json.email }}

Then open the node's Settings tab (the second tab inside the node, holding node-level behavior rather than parameters — this is Chapter 23 material):

• Retry On Fail: on
• Max Tries: 3
• Wait Between Tries (ms): 2000
• On Error: Continue (using error output)

That last setting is the important one. Retries absorb transient failure — a dropped packet, a momentary 500 from the provider — by simply trying again after a short wait. But if the enrichment service is genuinely down, its failure must not take lead capture down with it: a lead with no company data is still a lead you want. Continue (using error output) gives the node a second, red output connector that fires instead of raising an error, so the pipeline keeps flowing (Chapter 23).

Both connectors — the normal (success) output and the red (error) output — feed one Edit Fields (Set) node named Merge Enrichment. That single convergence node is what keeps the rest of the workflow simple: whichever way the enrichment call turned out, exactly one canonical lead record comes out of Merge Enrichment, and every later step reads its fields from there. Set Mode to Manual Mapping, Keep Only Set Fields on, and map both the original lead and the API response into one record:

The $('Node Name') syntax reaches back to any earlier node's output regardless of what sits between them — Chapter 17's single most useful trick, and the reason you renamed your nodes. It also does the graceful-degradation work here: on the success path $json holds the API response, so $json.company_name and $json.employee_count fill in; on the error path $json holds only an error object, so both fall through the || to the form's own company and a flat 0. Either way, one complete record leaves the node — which is why you did not need a separate fallback node at all. Replace company_name and employee_count with whatever your provider actually returns; run Execute step once and read the real response shape in the output panel rather than trusting the provider's docs (Chapter 22's first rule: look at the actual data, not the documentation about the data).

If this failed: a 401 or 403 means the credential is wrong or the header name does not match what the provider expects — open the credential and check both (Chapter 11). A 429 means you are being rate-limited; your retry spacing already helps, and if it persists, Chapter 24's pacing patterns are the cure. A response whose shape you guessed wrong will not throw — it produces undefined values that surface as blanks downstream, which is exactly why you inspect the real output now instead of at 2 a.m.

Canvas checkpoint: On form submission → Normalize Lead → Enrich Lead → Merge Enrichment, with both of Enrich Lead's outputs — the normal one and the red error one — wired into Merge Enrichment, which is the single node Stage 4 reads from.

Stage 4: Deduplicate Against the Data Table

People resubmit forms — twice on a slow connection, again next week when they forget. Without a memory, every resubmission would re-enrich, re-notify, and re-create a CRM record. The data table is that memory (Chapter 20).

Add a Data Table node, rename it Find Existing, and set Operation to Get row(s), Data Table to leads, with one filter condition: column email, condition Equals, value {{ $json.email }}. Then open its Settings tab and turn Always Output Data on.

Watch out: Without Always Output Data, a Get that matches nothing outputs nothing, and a node handed no input items simply never runs (Chapter 16) — so your "this lead is new" branch would silently never fire, and you would spend an hour convinced the IF node was broken. With the setting on, an empty result becomes one empty item, which the next node can actually test. This is the single most common trap in dedupe builds.

Add an IF node (Chapter 9) named Is New Lead? with one condition: type Boolean, value {{ $json.isEmpty() }}, operator is true. The isEmpty() helper (Chapter 17's data-type extensions) returns true only for that empty placeholder item — meaning no existing row matched, meaning the lead is genuinely new.

The false branch is the duplicate path. Give it a Data Table node named Mark Duplicate Seen: Operation Update row(s), matching email equals {{ $('Merge Enrichment').item.json.email }}, setting status to duplicate. Let the branch end right there — no Slack message, no CRM write. Duplicates get recorded, never amplified.

The true branch continues the pipeline. Its first node is a Data Table node named Save Lead: Operation Insert row(s), table leads. One subtlety here governs the rest of the build: Find Existing was a Get, and a Get replaces the item with its query result — so at this node $json is the empty placeholder, not your lead. The rule from here on is therefore: whenever a step needs the lead's own fields, read them from $('Merge Enrichment') (the canonical record) or, for the segment computed next, from $('Score Lead') — a back-reference by node name never goes stale the way $json does. Map the insert accordingly: email = {{ $('Merge Enrichment').item.json.email }}, name = {{ $('Merge Enrichment').item.json.name }}, company = {{ $('Merge Enrichment').item.json.company }}, employees = {{ $('Merge Enrichment').item.json.employees }}, created_at = {{ $('Merge Enrichment').item.json.received_at }}, and status = new. Leave segment blank; Stage 5 computes it and writes it back on the status update. Note there is no message column — the lead's free-text message is deliberately not stored, which is why a later step reaches back to Merge Enrichment for it.

Tip: If you would rather not maintain a separate insert and update, the Data Table node's Upsert row(s) operation does both in one node — it updates the row when the email key matches and inserts when it does not. It is tidier, but the explicit Get → IF → Insert/Update split above is worth building at least once, because it makes the "is this new?" decision visible on the canvas, which is what you want while you are still learning to trust the machine.

Test the whole chain twice with Execute workflow. The first run should take the true branch and insert a row (confirm it in the Data tables area); the second run, with the same pinned submission, should take the false branch. Watching an execution walk a specific path across the canvas, node by node, is the core loop of Chapter 22.

Canvas checkpoint: the converged enrichment stream feeds Find Existing → Is New Lead?, which splits into Mark Duplicate Seen (false, a dead end) and Save Lead (true, continuing).

Stage 5: Score and Route

Now decide what each new lead deserves — a scoring node, then a Switch that sends it down the right branch.

Add an Edit Fields (Set) node after Save Lead named Score Lead, Mode Manual Mapping, Keep Only Set Fields off (so the lead's existing fields pass through — the Insert echoed the row it just wrote, so $json is your lead again at this node), adding a single field, segment (String):

{{ $json.employees >= 200 ? 'high' : ['gmail.com','yahoo.com','hotmail.com','outlook.com'].includes($json.email.split('@').pop()) ? 'nurture' : 'standard' }}

Read it inside-out with Chapter 17 open: two hundred or more employees is a high-value lead; a free-mail domain with no real company behind it is a nurture lead; everyone else is standard. The thresholds and domain list are yours to tune — the branching structure is the transferable part.

Add a Switch node (Chapter 9) named Route by Segment, Mode Rules, with three rules, each a String Equals test on {{ $json.segment }}: high (rename its output High value), standard (Standard), nurture (Nurture). In the node's options, enable a Fallback Output so any unexpected segment value lands somewhere instead of vanishing, and wire that fallback into the Standard path — the safe default for a lead you could not classify.

The standard path

Two nodes in sequence. First your CRM node — for HubSpot, add the HubSpot node, Resource Contact, the create-or-update operation, mapping email, name, and company from {{ $('Score Lead').item.json.email }} and friends (Chapter 12's catalog mechanics; every CRM node offers the same mapping form). Mapping through the back-reference rather than $json is what lets you clone this exact node onto the other branches, where $json will be something else entirely. Name it Create CRM Contact. Second, a Slack node named Notify Sales: Operation Send Message, Channel your sales channel. Build the text from Merge Enrichment — the message never got a table column, so this is the last node that still holds it:

New lead: {{ $('Merge Enrichment').item.json.name }} ({{ $('Merge Enrichment').item.json.email }}) — {{ $('Merge Enrichment').item.json.company || 'no company' }}. "{{ $('Merge Enrichment').item.json.message }}"

Finish the path with a Data Table node named Mark Synced: Operation Update row(s), matching email equals {{ $('Merge Enrichment').item.json.email }} (a back-reference again, because $json here is the Slack node's reply, not the lead), setting status = synced and segment = {{ $('Score Lead').item.json.segment }}.

The nurture path

Just two nodes: a clone of Create CRM Contact (tag it with whatever low-priority property your CRM uses) and a clone of Mark Synced. No Slack message — nurture leads should never page a human at their desk.

The high-value path: human approval

This branch is what makes the machine trustworthy. Big leads get a human decision before anyone is celebrated or assigned, using the pause-and-resume pattern from Chapter 9.

Add a Slack node named Ask for Approval: Operation Send and Wait for Response, Channel your sales channel, Response Type Approval. In the approval options, pick the mode that shows both an approve and a disapprove button, so the false branch you are about to build is actually reachable. Message:

High-value lead needs review: {{ $('Merge Enrichment').item.json.name }} at {{ $('Merge Enrichment').item.json.company }} ({{ $('Merge Enrichment').item.json.employees }} employees). Claim it?

When this node runs in production, the execution parks itself in a waiting state — visible in the executions list with a waiting indicator (Chapter 21) — posts a Slack message carrying approve and disapprove buttons, and resumes the instant someone clicks. The chosen decision arrives on the node's output at {{ $json.data.approved }} as a boolean.

Tip: In the node's options, set a response timeout so an ignored message eventually resumes on its own instead of parking forever. Route the timed-out case the same way you route a disapproval — an unclaimed lead after a couple of days is itself a decision, and a workflow that waits indefinitely is a workflow you will eventually forget is running.

Follow it with an IF node named Approved?: Boolean, {{ $json.data.approved }}, is true — here $json is the approval reply, so read data.approved straight from it. The true branch gets its own Create CRM Contact clone (mark it high priority in your CRM's terms), a celebratory Notify Sales clone, and a Mark Synced clone; because all three read the lead through $('Merge Enrichment') and $('Score Lead') rather than $json, they keep working even though the approval step just overwrote $json with its own reply. The false branch gets a single Data Table update — Operation Update row(s), matching email equals {{ $('Merge Enrichment').item.json.email }}, setting status = rejected — so the lead stays queryable in the table, but nothing else happens to it.

If this failed: channel_not_found from Slack means the bot has not been invited to the channel, or the credential lacks the scope to post there (Chapter 11). An approval message whose buttons do nothing usually means someone clicked after the workflow was deactivated — resumes only work while the workflow is active. If the Switch funnels everything into one output, execute Score Lead alone and stare at the literal segment value it produced; a stray space or a casing mismatch against your rule is almost always the cause (Chapter 22).

Canvas checkpoint: Save Lead → Score Lead → Route by Segment, fanning into three branches — the approval chain, the standard chain, and the nurture chain — each ending in a data-table status update. That is the complete intake workflow. Rename anything still wearing a default name, and drop a sticky note over each stage (Chapter 8) before you move on.

Stage 6: The Daily Digest

Open Lead Machine — Daily Digest. This workflow reads the same data table the intake workflow writes. The two never call each other; the table is the handshake between them, which is exactly why you built the intake workflow to record everything it touched.

Add a Schedule Trigger (Chapter 7): Trigger Interval Days, Days Between Triggers 1, Trigger at Hour 8, minute 0. Check the workflow's timezone in its settings first — schedules fire in the workflow's configured timezone, and a mismatch there is one of Chapter 7's classic "why did it run at the wrong hour" gotchas.

Add a Data Table node named Fetch Recent Leads: Operation Get row(s), table leads, filter created_at Greater Than {{ $today.minus({ days: 1 }).toISO() }}. $today is midnight of the current day (Chapter 17), so subtracting one day gives midnight yesterday — the filter then captures everything created since. Set the row limit comfortably above your busiest expected day.

As in Stage 4, turn Always Output Data on for Fetch Recent Leads so an empty day still produces a testable item. Then add a Limit node (Chapter 18) named Just One immediately after the fetch, Max Items 1. This looks pointless and is not: a Slack node runs once per input item, so without it a thirty-lead day would fire thirty identical digests. Limit collapses the stream to a single item so the digest sends exactly once — and because the message text below pulls its data with .all() (which reads every row the fetch produced, regardless of how many items flow through the node right now), that one message still lists every lead.

Follow Just One with an IF node named Any Leads?, condition {{ $json.isEmpty() }} is false. On the true branch, a Slack node named Send Digest, Operation Send Message:

Lead digest — {{ $('Fetch Recent Leads').all().length }} new lead(s) since yesterday:
{{ $('Fetch Recent Leads').all().map(i => '• ' + i.json.name + ' — ' + (i.json.company || 'n/a') + ' [' + i.json.segment + ' / ' + i.json.status + ']').join('\n') }}

The .all() call gathers every item the fetch node produced, and the map-and-join builds one bullet per lead — an expression-only aggregation drawn straight from Chapters 16 and 17. If you prefer clicks to code, a Summarize node grouping by segment gives you a shorter count-based digest instead (Chapter 18). On the false branch, either end silently or send a one-line "No new leads yesterday" — teams genuinely disagree on whether a quiet channel is reassuring or worrying, so pick the one your team will read.

Test with Execute workflow — a schedule trigger fires immediately under a manual run — and confirm the message lands in Slack looking the way you want.

If this failed: several identical digests in the channel means the Limit node is missing or wired after the Slack node instead of before it. A header with no bullets, or a count that is off by a day, is almost always the date filter meeting a timezone mismatch — confirm the workflow's timezone matches the one $today resolves in. A digest that never arrives on a day you know had leads is the IF on the wrong branch; execute Fetch Recent Leads alone and check whether its rows actually cleared the created_at filter (Chapter 22).

Canvas checkpoint: Schedule Trigger → Fetch Recent Leads → Just One → Any Leads?, whose true branch ends in Send Digest.

Stage 7: The Error Workflow

Everything so far handles the failures the workflow can see coming: a flaky enrichment call, a duplicate submission, an unclassifiable segment. An error workflow (Chapter 23) is the net underneath all of that — it runs whenever a production execution of a linked workflow dies in a way nothing caught.

Open Ops — Error Handler. Add an Error Trigger node; it takes no configuration at all. Follow it with a Slack node named Alert Ops posting to your alerts channel:

Workflow failed: {{ $json.workflow.name }}
Error: {{ $json.execution.error.message }}
Failed node: {{ $json.execution.lastNodeExecuted }}
Execution: {{ $json.execution.url }}

The Error Trigger's payload includes a direct link to the failed execution, so whoever gets paged jumps straight into the Chapter 22 debugging loop instead of hunting for the run. Save and activate this workflow.

Now link it. In Lead Machine — Intake, open the workflow menu (the ⋯ in the top bar), choose Settings, and set Error Workflow to Ops — Error Handler. Do the same for the digest. One error handler serves the whole project — that is the intended pattern, not a corner cut to save nodes.

Test it for real: temporarily break the enrichment URL, activate intake, submit the production form once, and confirm the Slack alert arrives with a working link. Then fix the URL. An error path you have never triggered is a decoration, not a safety net (Chapter 23 says this; it is worth the repetition).

Watch out: The error workflow fires only for production executions — activated workflows responding to real events. Manual test runs in the editor surface their errors to you directly on the canvas instead of calling the handler. If you "tested" the error workflow by clicking Execute workflow and saw no alert, that is exactly why, and the handler is probably fine.

Stage 8: Time-Saved Instrumentation

The Lead Machine replaces real minutes of human labor per lead: reading the submission, looking up the company, checking whether you have seen them before, creating the CRM record, telling the channel. Estimate that honestly — say ten minutes per lead — and record it in the intake workflow's settings: back in ⋯ > Settings, find the estimated time-saved-per-execution field and enter your number. Do the same for the digest (a few minutes a day of someone compiling a summary by hand).

From then on, the Insights view (Chapter 25) multiplies your per-execution estimate by the count of real production executions and reports cumulative time saved — the single number you hand to whoever asked whether this automation was worth building. How much of Insights your instance shows varies by plan and deployment; the per-workflow estimate is the part you own outright. Keep it defensible: time a colleague doing the task once by hand, use that, and resist the urge to round up. A believable small number beats an impressive number nobody trusts.

Stage 9: Activate and Own the First Week

The launch checklist, straight from Chapter 10:

1. Unpin everything. Pinned data in an active workflow means every production run replays your test submission forever. Walk the canvas and clear every pin icon.
2. Check execution-saving settings. In ⋯ > Settings, confirm both successful and failed production executions are being saved, so Chapter 21's executions list actually has records to inspect during week one. Once volume climbs you may stop saving successes to save space — but not yet.
3. Activate both Lead Machine workflows with the toggle in the top bar. The error handler is already active from Stage 7.
4. Swap in the Production URL. Publish the form's Production URL — on your site, in your email signature, wherever leads originate. The Test URL stops responding the moment you close the editor, so anything still pointing at it goes dark silently.
5. Submit one real lead yourself through the production URL and follow it end to end: the executions list shows a run, the data table gains a row, the CRM gains a contact, Slack gets its message. If any link in that chain is missing, fix it before real leads arrive, not after.

Then, the first week of ownership — the part most people skip and later regret:

• Days 1 to 3, every morning: open the executions list (Chapter 21), filter by status Error first and read every one, then spot-check a few successes. Open one success and walk its canvas view to confirm leads are taking the branches you expect.
• Watch the enrichment node for retry patterns. The occasional retry is healthy. A consistent retry-then-fail means you need Chapter 24's pacing patterns or a conversation with your provider about limits.
• Watch the waiting executions. High-value leads sitting unapproved for days means your timeout is too generous, or your sales channel is too quiet to be a real gate.
• Verify the digest against reality at least twice: does Tuesday's message match the rows the table actually gained on Monday? Off-by-one date filters announce themselves precisely here, and nowhere earlier.
• Tune the score. If sales says the high-value branch is too noisy or too sparse, change the employee threshold in Score Lead — one expression, no re-architecture.
• End of week: check Insights. Execution count, failure rate, time saved. That trio is your first report, and it is the argument for building the next machine.

What You Just Proved

Every technique in this build came from a chapter you had already read: triggers and schedules (7), canvas craft and node naming (8), branching, waiting, and human approval (9), test-and-activate discipline (10), credentials (11), catalog nodes (12), HTTP against an arbitrary API (13), webhook mechanics (14), item thinking (16), expressions (17), transformation (18), remembered state in a data table (20), executions as the system of record (21), the debugging loop (22), retries, error outputs, and the error workflow (23), graceful degradation and pacing (24), and proving value (25). The Lead Machine is those chapters composed and nothing more — which is the actual lesson of the chapter. Production-grade automation is rarely a clever node. It is ordinary nodes arranged with discipline, tested until you trust them, and watched for a week after they go live.

Chapter 37 (Worked Project 2: The Support Copilot) rebuilds this same end-to-end rigor around an AI agent, so you can see which parts of the discipline are universal and which are specific to deterministic work. Chapter 38 (The Recipes Cookbook) lifts the reusable patterns you just exercised — dedupe-with-a-table, approve-before-write, digest-from-state — out of this project and presents them as standalone recipes you can drop into the next build.

Worked Project 2: The Support Copilot (AI Agent End to End)

Worked Project 1 (see Chapter 36, Worked Project 1: The Lead Machine) proved you can build classic deterministic automation. This project proves you can build the other kind: an AI system that reasons over your own knowledge, takes real actions, and still behaves like production software rather than a demo. You will build a support copilot — a chat assistant your support team talks to, which answers questions from your company documentation, opens tickets on request, and drafts customer replies that a human must approve before anything leaves the building.

Everything here exercises Volume F (AI), leaning on Volume E (reliability) and Volume G (operations) exactly as the chapters teach them. Every stage cites its teaching chapter, and at five checkpoints you will pause and compare your canvas — the visual editor surface where workflows are built (Chapter 4, A Guided Tour of the Workspace) — against a described state. If your canvas does not match, fix it before moving on; later stages assume earlier ones are correct.

The Destination

The finished system is not one workflow. It is five small workflows that cooperate, plus an evaluation harness wired into one of them — the same decomposition instinct Chapter 9 (Flow Control: Branching, Looping, Waiting, and Sub-workflows) teaches for classic automation, applied to AI.

A few terms, briefly, since this chapter uses them constantly. A vector store is a database that stores text as embeddings — lists of numbers that capture meaning — so you can retrieve passages by similarity rather than keyword (Chapter 29, RAG: Giving AI Your Knowledge). RAG (retrieval-augmented generation) is the pattern of fetching relevant passages and handing them to a language model so it answers from your facts instead of its memory. MCP (Model Context Protocol) is an open standard that lets AI applications discover and call tools you expose (Chapter 30, Trustworthy AI: Evaluations, Cost Control, and MCP Exposure). An AI Agent is the n8n node that lets a model decide, per conversation turn, which attached tools to call (Chapter 28, The AI Agent Node: Tools, Memory, and Guardrails).

Prerequisites and Ground Rules

Before you start, you need three things in place.

First, a chat-model credential. Create a credential for whichever model provider you use — the process is Chapter 11 (Credentials from Zero). Any mainstream provider works; this build never depends on a specific one.

Second, a vector store decision. n8n ships the Simple Vector Store, an in-memory store that is perfect for learning and useless for production, because its contents live in the n8n process's memory and vanish on restart. For this project, start with the simple store so nothing external blocks you, and plan to swap in a persistent store (Qdrant, Pinecone, Postgres with pgvector, Supabase, and others have dedicated nodes — Chapter 29 compares them) before promotion. The swap is a node replacement, not a redesign.

Third, a place for the build to live. Put all five workflows in one project or folder with the Copilot – name prefix, per the hygiene rules in Chapter 10 (Test, Fix, Activate, and Keep It Tidy). If you are on a team plan, a dedicated project also gives you clean access control later (Chapter 34, Access, Security, and Secrets for Teams).

Tip: Decide now what the copilot is allowed to do without a human. In this build the agent may answer questions and create tickets autonomously, but may never send anything to a customer on its own. Writing that sentence down before you build is the cheapest guardrail you will ever install (Chapter 28's guardrail-first discipline).

Stage 1: The Knowledge Pipeline

The copilot is only as good as what it can retrieve, so the first workflow ingests your documentation. This is the standing-pipeline pattern from Chapter 29: load documents, split them into chunks, embed each chunk, insert into the vector store.

Create a new workflow named Copilot – Docs Ingestion. Start it with a Manual Trigger — the click-to-run trigger from Chapter 7 (Triggers: Deciding When Work Happens) — because during development you want to run ingestion deliberately, not on a schedule.

Next, fetch the documents. Where they come from is your choice: a Google Drive folder, a Notion space, files fetched over HTTP, or files uploaded straight into the workflow. Whatever the source, the goal is a stream of items each carrying one document as binary data — file content traveling alongside the item, as Chapter 20 (Files and Remembered State: Binary Data and Data Tables) explains. A Google Drive folder of PDFs and text exports is a common, low-friction choice: one node lists the folder, a second downloads each file.

Now add the vector store node and set its operation to insert documents. When you do, you will see the cluster-node architecture from Chapter 26 (AI Foundations and the Cluster-Node Architecture) in action: the vector store node sprouts attachment points below it for sub-nodes, which are helper nodes that plug into a root node instead of joining the left-to-right data flow. Attach three:

• A document loader (the default data loader), which converts your binary files into text documents. Point it at the binary property your download node produced, and add metadata — at minimum the source filename — so every chunk remembers where it came from. Retrieval that can cite its source is debuggable retrieval.
• A text splitter (the recursive character splitter is the sensible default), which cuts long documents into chunks. Chapter 29 covers chunk-size tradeoffs; a chunk of roughly a paragraph to a page, with modest overlap, is a fine starting point.
• An embeddings sub-node, which turns each chunk into a vector using your model provider credential. Whatever embedding model you choose here, you must use the same one at retrieval time — mixed embedding models silently retrieve garbage.

Run the workflow once with a handful of real documents. Open the execution (Chapter 21, Executions: The System of Record) and confirm the vector store node reports inserted chunks.

One reliability matter before you call this stage done, straight from Chapter 24 (Reliability Patterns: Idempotency, Pacing, and Recovery): re-running ingestion naively inserts every chunk again, and duplicate chunks degrade retrieval. The simple fix while you are learning is to clear the store before each full ingestion run — the Simple Vector Store's insert operation has a clear-store option, and most persistent stores let you delete by namespace or collection. The grown-up fix, when you move to a persistent store, is incremental ingestion keyed on document identity. Choose one now and note it in a sticky note on the canvas (Chapter 10's documentation habit).

Checkpoint 1. Your Copilot – Docs Ingestion canvas shows: Manual Trigger → document source node(s) → vector store node in insert mode, with three sub-nodes hanging beneath the vector store — document loader, text splitter, embeddings. The last execution succeeded and shows a non-zero chunk count. If the sub-nodes are attached to the wrong root or the execution shows zero documents, fix that now; every later stage retrieves from this store.

Stage 2: The Conversation Spine

Create the second workflow, Copilot – Support Chat. This is the heart of the system, and its first version is deliberately tiny: a trigger, an agent, a model, and memory. Tools come next stage.

Add a Chat Trigger — the trigger that gives a workflow a chat interface (Chapter 7 catalogs it; Chapter 28 uses it). In the editor it opens a chat panel for testing; once the workflow is active it can also serve a hosted chat page or an embeddable widget if you enable public availability in the trigger's options. Leave it non-public for now: this copilot's users are your support staff, and you will decide the access story at promotion time (Chapter 34).

Connect the Chat Trigger to an AI Agent node. Two sub-nodes make it functional:

• A chat model sub-node using your provider credential. Chapter 30's cost lens applies from the first minute: pick a mid-tier model for development. You can evaluate a cheaper or stronger model later with the harness from Stage 6, which is the honest way to choose.
• A memory sub-node — the simple buffer memory, which keeps the last several turns of a conversation. Memory needs a session key so it knows which conversation is which; the Chat Trigger supplies a session identifier, and the default wiring uses it. The buffer length is a cost decision: every remembered turn is re-sent to the model on every new message (Chapter 30).

Watch out: If you ever swap the Chat Trigger for another entry point (a webhook, a sub-workflow call), memory silently breaks unless the new entry supplies a session key expression of its own. A memory node keyed on a value that is the same for everyone merges all users into one conversation — a confusing and privacy-relevant bug. Chapter 28 covers session-key discipline.

Now write the system message — the standing instructions the agent receives before every conversation, set in the AI Agent node's options. Treat it as the product specification it is. A workable first draft:

You are the internal support copilot for [company]. You answer support agents' questions using the company knowledge base tool; always search it before answering questions about products, policies, or procedures, and say plainly when it contains no answer — never invent one. When asked to open a ticket, use the ticket tool and report the ticket ID back. When drafting a reply to a customer, state clearly that the draft will be sent for human approval and will not go to the customer directly.

It references tools that do not exist yet; that is fine — you are writing the contract they will fulfill.

Open the chat panel and talk to it. It will answer from the model's general knowledge, with memory across turns but with no access to your docs. Verify memory works: tell it your name, ask two questions, then ask it your name.

Checkpoint 2. Your Copilot – Support Chat canvas shows Chat Trigger → AI Agent, with exactly two sub-nodes beneath the agent: a chat model and a memory node. In the chat panel, the agent responds and recalls earlier turns in the same session. The execution list shows one execution per chat message — confirming what Chapter 21 teaches: every chat turn is an ordinary execution you can inspect.

Stage 3: Tools — Retrieval and Ticket Creation

An agent without tools is a chatbot. This stage attaches two.

The retrieval tool

Add a vector store node as a tool on the AI Agent — the vector store node offers a retrieval-as-tool operation designed exactly for this (Chapter 29). Configure it to point at the same store, with the same embedding sub-node settings, as your ingestion workflow. Give the tool a name like company_knowledge_base and a description the model will read when deciding whether to use it: "Searches [company]'s internal documentation for product details, policies, and procedures. Use for any company-specific question." Tool descriptions are prompts — Chapter 28's rule that a vague description produces a tool the agent never calls, or calls constantly.

Depending on configuration, retrieval either feeds raw passages to the agent or summarizes them with a model first; start with raw passages and a handful of results, and tune with evidence later.

Test in the chat panel with a question only your docs can answer. Then open the execution and inspect the agent's steps — the execution view shows each tool call, its input, and its output (Chapter 22, The Debugging Craft, walks the AI-specific parts of this view). Confirm the agent actually called the retrieval tool and that the returned chunks contain the answer. If the chunks are irrelevant, your problem is ingestion (chunking, embeddings), not the agent — Chapter 29's debugging order.

The ticket tool

Tickets need a home. Create a Data Table — n8n's built-in lightweight tables (Chapter 20) — named tickets, with columns such as subject, summary, customer_email, priority, status, draft_reply, and created_at. In a real deployment this might be your helpdesk's API instead; the Data Table keeps the project self-contained, and swapping it later changes one node.

Now build the tool as a sub-workflow, the pattern Chapter 9 teaches and Chapter 28 applies to agents: a separate workflow the agent invokes like a function. Create Copilot – Create Ticket, starting with the sub-workflow trigger (the "when executed by another workflow" trigger). Define its expected inputs explicitly — subject, summary, customer_email, priority, and optionally draft_reply for a proposed customer response. Explicit input schemas matter double for agent tools: the schema is what tells the model what arguments to supply.

Inside the sub-workflow: validate the inputs (an IF node rejecting an empty subject, per Chapter 23's fail-early advice), insert a row into the tickets Data Table with status set to pending_approval when a draft reply is present and open otherwise, and end with a Set node returning a compact result — the ticket ID and a one-line confirmation. Whatever the last node outputs is what the agent receives; return small, clean text, not the whole row.

Back in Copilot – Support Chat, attach the tool that calls an n8n sub-workflow to the AI Agent, point it at Copilot – Create Ticket, map the tool's parameters to the sub-workflow inputs, and describe it: "Creates a support ticket. Use when the user asks to open, file, or escalate a ticket. Provide a short subject, a summary of the issue, the customer's email if known, and a priority of low, normal, or high."

Test the full loop in the chat panel: describe a customer problem, ask the copilot to open a ticket and draft a reply, and confirm it reports a ticket ID. Check the Data Table for the new row with status = pending_approval.

Checkpoint 3. The AI Agent now has four sub-nodes: chat model, memory, the vector-store retrieval tool, and the sub-workflow ticket tool. A doc question triggers a visible retrieval call in the execution log; a ticket request produces a Data Table row and a reported ticket ID. Copilot – Create Ticket exists as its own workflow: sub-workflow trigger → validation → Data Table insert → Set (return). If ticket requests answer conversationally without a row appearing, the tool description or input schema is the culprit — the agent cannot call what it cannot understand.

Stage 4: The Human Gate

Here is the design decision that makes this system trustworthy: drafted customer replies never send themselves. You might be tempted to put the approval inside the ticket sub-workflow, but think through the timing — an agent tool call waits for the sub-workflow to finish, and a human approval can take hours. A tool that blocks a chat for hours is broken. So the gate lives in its own workflow, decoupled by the Data Table: the ticket tool returns instantly, and a dispatcher picks up pending drafts on its own clock. This is the queue-and-worker decoupling pattern from Chapter 24, applied to human latency instead of API latency.

Create Copilot – Reply Dispatcher. Its trigger is a Schedule Trigger (Chapter 7) running every few minutes. The flow:

1. Fetch pending work. Query the tickets Data Table for rows where status is pending_approval — and take only the first match. One row per run keeps the waiting step simple: an execution that pauses for one approval and resumes once is easy to reason about, while one execution juggling several parked approvals is not. The schedule sweeps up the rest on later runs.
2. Claim the row. Immediately update its status to awaiting_decision before doing anything else. This is Chapter 24's idempotency claim — idempotent meaning safe to run again without doubling its effects: if the schedule fires while an approval is still outstanding, the row is no longer pending and cannot be dispatched twice.
3. Ask a human. Use a messaging node's send-and-wait operation — Slack and email nodes offer an operation that sends a message and pauses the execution until someone responds, with an approve/decline button style built in (the waiting mechanics are Chapter 9's Wait-node family). Send the supervisor the ticket subject, the customer email, and the full draft reply, and ask for approval. The execution parks — consuming no resources — until the decision arrives, even if that is tomorrow.
4. Branch on the decision with an IF node (Chapter 9). Approved: send the draft to the customer via your email node, then update the row to sent. Declined: update the row to rejected, optionally notifying the requesting support agent so the reply can be rewritten by a person.

Watch out: The approval request goes to an internal channel and the approved text goes to the customer — two different sends, two different nodes, easy to cross-wire at 5 p.m. Test with your own address as the "customer" until you have seen both messages land where they should. And keep the send node after the IF's approved branch, never before it; a node placed before the gate has already run by the time anyone decides anything.

Test end to end: in chat, ask the copilot to open a ticket with a drafted reply; run the dispatcher manually instead of waiting for the schedule; approve the Slack (or email) prompt; confirm the customer email arrives and the row flips to sent. Then do it again and decline, confirming nothing sends.

Checkpoint 4. Copilot – Reply Dispatcher shows: Schedule Trigger → Data Table query → Data Table update (claim) → send-and-wait approval → IF → two branches (send + mark sent; mark rejected). In the executions list you can see a dispatcher execution sitting in a waiting state while an approval is outstanding — that parked state is Chapter 21's waiting status, and seeing it confirms the gate is real.

Stage 5: Exposing One Capability over MCP

Your copilot's ticket tool is useful beyond your chat. MCP lets other AI applications — a desktop assistant, an IDE agent, another company system — discover and call tools you choose to publish. Chapter 30 covers the trust model; here you apply it narrowly: expose ticket creation, and nothing else.

Create Copilot – MCP Server. Its trigger is the MCP Server Trigger, a trigger node that behaves like a webhook endpoint (Chapter 14, Webhooks In Depth) speaking the MCP protocol. Like the agent, it takes tool sub-nodes — attach the same sub-workflow-calling tool, pointed at the same Copilot – Create Ticket workflow, with the same description. One sub-workflow now serves two masters, which is exactly why Stage 3 built it as a sub-workflow: single implementation, multiple front doors.

Configure authentication on the trigger — at minimum a bearer token, a secret string the client must present with every request, stored as a credential and never pasted into node parameters (Chapter 34's secrets discipline). The trigger exposes a test URL and a production URL, the same split Chapter 14 teaches for webhooks: the production URL only answers once the workflow is active.

Test with any MCP-capable client: register the production URL and token, confirm the client lists a single tool, and have it create a ticket. The row appears in your Data Table like any other, and — pleasingly — if the MCP-created ticket carries a draft reply, your Stage 4 approval gate governs it identically. External callers get the capability, not a bypass.

Watch out: Everything attached to an MCP Server Trigger is callable by whoever holds the URL and token. Do not attach the retrieval tool "while you're in there" unless you have decided that outside clients may read your internal knowledge base. Exposure is a governance decision, not a convenience (Chapter 30).

Checkpoint 5. Copilot – MCP Server shows the MCP Server Trigger with exactly one tool sub-node. An external client has successfully created one ticket, visible in the Data Table with a source you can distinguish (add a source column set by the tool if you want the audit trail — Chapter 25 will thank you).

Stage 6: The Evaluation Harness

You will want to change the system message. Everyone does, weekly. The question Chapter 30 forces is: how do you know the new prompt is better and not just different? The answer is a regression dataset and n8n's evaluations feature. (How much of the feature your instance carries varies by plan and version; the discipline below holds regardless.)

First, the dataset. Create a Data Table named copilot-eval, with columns for the input question, the expected answer or expected behavior, and a category. (The evaluations feature reads its dataset from a Data Table by default; Google Sheets is the alternative source, and the only one on older n8n versions.) Seed it with fifteen to thirty real cases: doc questions with known answers, a question your docs cannot answer (expected behavior: says so, does not invent), a ticket request (expected behavior: calls the ticket tool), and a couple of adversarial phrasings. Real transcripts from your own testing are the best source.

Then wire evaluation into Copilot – Support Chat itself, so you test the real workflow rather than a copy. Add an Evaluation Trigger alongside the Chat Trigger — this second trigger fetches dataset rows one at a time and feeds each as input to the same agent path. Both triggers coexist; normal chats use one door, evaluation runs use the other. After the agent, add the Evaluation node twice on the evaluation path: once with its set-outputs operation, which writes the agent's actual answer back beside the dataset row, and once with set-metrics, which scores the run. n8n offers built-in metric styles — including model-graded correctness, where a judge model compares actual against expected, and checks on which tools were called — plus custom metrics you compute yourself. Use a branch that checks whether the current execution is an evaluation run to keep this machinery out of live chats; the Evaluation node's check-if-evaluating operation provides exactly that branch.

Run a full evaluation from the workflow's evaluations tab and look at the scores. That first run is your baseline. Now the discipline, which is the entire point: before every system-message change, model swap, retrieval tweak, or chunking change, run the evaluation; make the change; run it again; compare. A change ships only if scores hold or improve, and any dataset row that regresses gets read, not averaged away. When a live conversation goes wrong in a new way, add it to the dataset — the harness grows with your scar tissue, the same executions-as-evidence habit Chapter 21 builds.

Tip: Evaluation runs cost real model tokens — every row is a full agent run, plus judge calls. Keep the dataset lean and pointed rather than huge, and run it at decision moments rather than on a schedule. Chapter 30's cost framing applies to the test harness just as much as to production.

Stage 7: Promotion to Production

The system works. Making it production is Volume E and G work, and none of it is optional.

Error handling for AI failure modes

Chapter 23 (Error Handling: Retries, Error Branches, and Error Workflows) gives you three layers; apply each to the ways AI specifically fails:

Build one small error workflow — an Error Trigger node feeding a Slack or email alert with the failing workflow's name and execution link (Chapter 23's recipe) — and assign it in the settings of all of the copilot workflows. A silent overnight failure of the dispatcher means approved replies never send; that must page someone.

Cost and health monitoring

Open any agent execution and you can see token usage for the AI nodes — that per-run visibility is your unit-cost ground truth (Chapters 21 and 30). For the aggregate view, use the Insights dashboard (Chapter 25, Monitoring, Insights, and Proving Value) to watch run volume, failure rate, and runtime trends, and set a spending alert or hard budget on the model provider's own dashboard — the provider's meter is the one that bills you. If unit cost creeps, the usual suspects are an over-long memory buffer, too many retrieval chunks, or a stronger model than the job needs; change one at a time and let the Stage 6 harness confirm quality held.

The activation pass

Run Chapter 10's activation checklist across the fleet: swap the ingestion Manual Trigger for a Schedule Trigger if your docs change regularly (or keep it manual and deliberate — a legitimate choice); confirm the simple vector store has been replaced by a persistent one and re-run ingestion into it; activate Copilot – Support Chat, the dispatcher, and the MCP server; confirm execution saving is on for successes and failures so Chapter 21's system of record is complete; decide the chat access story (hosted chat behind your team's access, or embedded internally); and check credentials are shared with the project, not owned by one person's account (Chapter 34). On n8n Cloud, give the instance an owner's once-over per Chapter 31 (Operating n8n Cloud Like an Owner); self-hosters should confirm the vector store and database survive a container restart (Chapter 32, Self-Hosting from Zero).

What You Practiced

You built a RAG ingestion pipeline and wired retrieval, action, and memory into one agent (Chapters 26–29); you split capabilities into sub-workflows and got reuse for free when MCP exposure needed the same tool (Chapters 9 and 30); you put a pausing human gate between AI drafts and customers (Chapters 9 and 23); you made prompt changes falsifiable with a regression dataset (Chapter 30); and you promoted it with error workflows, idempotent claiming, and cost telemetry (Chapters 21–25). When something misbehaves in production — and something will — Chapter 39 (The Troubleshooting Encyclopedia) indexes the symptoms, and Chapter 38 (The Recipes Cookbook) has variations on every pattern you just used.

The Recipes Cookbook

This chapter is a shelf of small, finished answers. Each recipe solves one task that operators actually search for in a normal week — "send a digest," "verify this webhook," "stop paying for duplicate API calls" — in a fixed format: the goal, the node chain, the one expression or setting you need verbatim, and the single gotcha that trips most people. Recipes deliberately do not re-teach theory. When a recipe leans on an idea, it names the chapter that owns it, and you should read that chapter the first time the idea is new to you. Expressions here use n8n's double-curly-brace language (Chapter 17); node chains read left to right, with → meaning "connect the output to the input."

Tip: Before adapting any recipe, run your trigger once and pin its output, so every downstream tweak replays the same sample data instead of hitting the live service again. Pinning is covered in Chapter 10 (Test, Fix, Activate, and Keep It Tidy).

Scheduling and digests

Trigger theory lives in Chapter 7; the shaping nodes (Aggregate, Summarize, Sort) live in Chapter 18.

1. Weekday-morning report at 8:00

Goal: Run a workflow every weekday at 8:00 in your local time. Chain: Schedule Trigger → your fetch nodes → Gmail (or any send node). Key setting: Schedule Trigger in cron mode with 0 8 * * 1-5, and set the workflow's timezone in Workflow Settings > Timezone. Gotcha: New workflows inherit the instance default timezone, which is often UTC — the schedule "works" but fires hours off until you set the timezone explicitly.

2. Collapse many items into one digest body

Goal: Turn twenty fetched records into one readable email instead of twenty emails. Chain: Fetch node → Aggregate → Gmail. Key expression: With Aggregate set to "All Item Data," the list lands in a data field, so the email body becomes {{ $json.data.map(i => '- ' + i.title).join('\n') }}. Gotcha: Forgetting Aggregate means the send node runs once per item (Chapter 16 explains why), and you spam yourself with one email per record.

3. A rolling "last 7 days" window

Goal: Fetch only records created since a week ago. Chain: Schedule Trigger → HTTP Request (or app node) with a date filter. Key expression: {{ $now.minus({ days: 7 }).toISO() }} as the filter value. Gotcha: A rolling window drifts: if a run fails or fires late, records can be counted twice or missed. For exactly-once coverage, store a high-water mark instead (recipe 30).

4. Monthly report on the first Monday

Goal: Fire once a month, on the first Monday. Chain: Schedule Trigger → IF → report chain. Key expression: Run daily and gate with an IF condition: {{ $now.weekday === 1 && $now.day <= 7 }}. Gotcha: Writing this as a single cron with both a day-of-month range and a day-of-week can behave as "either matches" in some cron implementations. The daily-run-plus-IF pattern is boring and unambiguous.

5. Counts by category

Goal: "12 new leads: 7 inbound, 3 referral, 2 paid." Chain: Fetch → Summarize → Aggregate → send. Key setting: Summarize with "Fields to Split By" set to your category field and an aggregation of Count. Gotcha: Summarize outputs one item per group, so you still need Aggregate (recipe 2) before composing a single message.

6. Say "nothing new" instead of going silent

Goal: Send a short "no items today" note rather than nothing, so people trust the digest is alive. Chain: Fetch → Aggregate → IF → two send branches. Key setting: Enable Settings > Always Output Data on the Aggregate node, then branch on {{ $json.data.length > 0 }}. Gotcha: Without Always Output Data, a zero-item fetch produces no items, downstream nodes never run, and the IF never gets a chance to fire the "nothing new" branch.

7. Stagger your schedules

Goal: Stop ten workflows all firing at the top of the hour and tripping rate limits together. Chain: No new nodes — just different Schedule Trigger settings. Key setting: Offset the minute field per workflow: 7 8 * * *, 13 8 * * *, and so on. Gotcha: Everyone types 0 for minutes by habit. On self-hosted instances the top-of-hour pileup also competes for the same worker capacity (Chapter 33).

Pagination and rate-limit backoff

The HTTP Request node and its built-in pagination are Chapter 13's territory; pacing and recovery patterns are Chapter 24's.

8. Follow a "next URL" until it runs out

Goal: Fetch every page when the API returns the next page's full URL. Chain: HTTP Request only. Key setting: In Options > Pagination, choose "Response Contains Next URL," set the next URL to {{ $response.body.next }}, and complete when {{ !$response.body.next }}. Gotcha: Leave the maximum-pages limit unset against a buggy API and you can loop forever. Always set a generous but finite cap.

9. Page-number pagination

Goal: Fetch ?page=1, ?page=2, and so on until the response is empty. Chain: HTTP Request only. Key expression: Pagination mode "Update a Parameter in Each Request," parameter page, value {{ $pageCount + 1 }} — $pageCount starts at zero. Gotcha: Off-by-one: forgetting the + 1 fetches page 0 twice on APIs that are 1-based, which shows up as mysterious duplicates downstream.

10. Cursor pagination

Goal: Pass along the cursor token each response hands you. Chain: HTTP Request only. Key expression: Update a parameter named cursor with {{ $response.body.meta.next_cursor }}, completing when that field comes back empty. Gotcha: Some APIs return the cursor in a header rather than the body; $response.headers is available in pagination expressions too, with header names lowercased.

Watch out: Runaway pagination is the classic way to burn an execution allowance or an API quota overnight. Cap the page limit, and add an interval between requests in the pagination options when the API is rate-limited.

11. Automatic retries on flaky calls

Goal: Survive the occasional timeout without failing the run. Chain: Any node — this is a node setting, not a new node. Key setting: On the node's Settings tab: Retry On Fail, with Max Tries and Wait Between Tries. Gotcha: The built-in wait between tries is short by design. For minutes-long backoff, use the error-output loop in the next recipe instead. Chapter 23 covers when retrying is safe at all.

12. Honor Retry-After on 429 responses

Goal: When the API says "too many requests," wait exactly as long as it asks. Chain: HTTP Request → IF → Wait → back into the HTTP Request (a loop), with the IF's other branch continuing normally. Key setting: In the HTTP Request's response options, enable "Include Response Headers and Status" and "Never Error"; branch on {{ $json.statusCode === 429 }} and set the Wait amount to {{ $json.headers['retry-after'] || 30 }} seconds. Gotcha: With headers-and-status enabled, your payload moves under $json.body — every downstream expression that read $json.someField must become $json.body.someField.

13. Pace a large batch

Goal: Send 500 records to an API that tolerates only a few calls per second. Chain: Fetch → Loop Over Items → HTTP Request → Wait → back to Loop Over Items; the "done" output continues the workflow. Key setting: Loop Over Items with a small batch size, and a Wait of a second or two inside the loop. Gotcha: The loop-back connection goes from the Wait node into Loop Over Items' input — new builders connect it to the wrong place and process only the first batch. Looping mechanics are Chapter 9.

14. One-at-a-time processing via sub-workflow

Goal: Guarantee strictly sequential processing with clean per-record error isolation. Chain: Fetch → Execute Sub-workflow → the sub-workflow does the risky work. Key setting: The Execute Sub-workflow mode that runs the sub-workflow once for each item. Gotcha: Each sub-run is a separate execution record — good for debugging (Chapter 21), but a 500-item batch creates 500 executions, which matters on plans metered by executions.

Spreadsheet sync

These recipes use Google Sheets as the example; the same shapes apply to the Excel-family nodes. Catalog navigation is Chapter 12.

15. Upsert rows by key

Goal: Add new rows and update existing ones in a single pass. Chain: Fetch → Google Sheets. Key setting: Operation "Append or Update Row" with "Column to Match On" set to your unique key column (an email or an ID). Gotcha: If the sheet already contains duplicate values in the match column, updates land on the first match only, and your "sync" silently diverges. Dedupe the sheet once before adopting this pattern.

16. Two-way diff between a sheet and an API

Goal: Know what exists only in the sheet, only in the API, or in both but changed. Chain: Google Sheets (read) → Compare Datasets ← HTTP Request (read); then act on each of the four outputs. Key setting: "Fields to Match" set to the shared key on both inputs. Gotcha: Compare Datasets treats "42" and 42 as different values. Normalize types first (Chapter 18) or every numeric column reports as "different."

17. A sheet as a lightweight task queue

Goal: Humans drop rows in; the workflow processes rows where Status is NEW and marks them DONE. Chain: Schedule Trigger → Google Sheets (read, filtered) → process → Google Sheets (update). Key setting: Read with a filter on the Status column; update using the row_number field the read operation returns. Gotcha: row_number is a position, not an identity. If someone deletes a row mid-run, every later row shifts and your update writes to the wrong line. Prefer updating by a key column when humans edit the sheet live.

18. Nightly mirror of an API list into a sheet

Goal: A sheet that always reflects current API state. Chain: Schedule Trigger → fetch (paginated, recipe 8) → Google Sheets (clear) → Google Sheets (append). Key setting: The Clear operation on the target sheet before appending fresh rows. Gotcha: Clear-then-append has a failure window: if the append fails, you are left with an empty sheet. Either upsert instead (recipe 15) or mirror into a staging tab and swap.

19. Enrich items from a lookup sheet

Goal: Attach, say, an account owner to each incoming lead using a mapping sheet. Chain: Trigger → Merge ← Google Sheets (read); Merge feeds the rest of the chain. Key setting: Merge in "Combine" mode, combining by "Matching Fields" on the shared key. Gotcha: Merge waits for both inputs; if the Sheets read returns zero rows, the combine can output nothing and the workflow appears to die silently. Item pairing is Chapter 16's subject.

20. Survive empty cells

Goal: Stop blank spreadsheet cells from breaking expressions. Chain: Any chain reading sheet data. Key expression: {{ $ifEmpty($json.phone, 'unknown') }}. Gotcha: Sheets nodes often return empty strings rather than missing fields, so "field exists" checks pass while the value is useless. $ifEmpty() treats both cases as empty.

Tip: A spreadsheet is a fine queue and a fine mirror, but a poor database: no locking, easy human edits, and type drift. When state matters, use n8n's Data Tables (Chapter 20) and keep the sheet as a human-friendly view.

File conversion

Binary data — how n8n carries files — is Chapter 20's subject.

21. CSV upload to JSON items

Goal: Turn an incoming CSV file into one item per row. Chain: Trigger with a file (webhook, email, Drive) → Extract from File. Key setting: Operation "Extract From CSV"; confirm the header-row option matches your file. Gotcha: Files exported from European locales often use semicolons as delimiters. If every row parses as one giant column, set the delimiter explicitly.

22. JSON items to an XLSX attachment

Goal: Send query results as a spreadsheet attachment. Chain: Fetch → Convert to File → Gmail. Key setting: Convert to File, operation "Convert to XLSX"; in the send node, reference the attachment's binary property name (default data). Gotcha: Nested objects become the text [object Object] in cells. Flatten items first with Edit Fields (Chapter 18) so every column holds a scalar.

23. Download a file from a URL

Goal: Fetch a PDF or image as a real file, not text. Chain: HTTP Request → whatever consumes the file. Key setting: In the HTTP Request's response options, set the response format to "File." Gotcha: Leave the format on autodetect and some servers return the bytes as mangled text; downstream nodes then see no binary property at all.

24. Branch on file type

Goal: Route images one way, PDFs another. Chain: File source → Switch → per-type branches. Key expression: {{ $binary.data.mimeType }} as the Switch value, matching on application/pdf, image/png, and so on. Gotcha: The property name (data here) must match whatever the upstream node used; check the binary tab of the source node's output first.

25. HTML report, PDF delivery

Goal: Produce a polished document from workflow data. Chain: Fetch → HTML node (build the report) → HTTP Request to an HTML-to-PDF conversion service → send. Key setting: The HTML node composes the document; n8n has no built-in PDF renderer, so conversion goes through a service you host or subscribe to. Gotcha: Inline all styles in the HTML — most converters ignore external stylesheets.

26. Multiple attachments on one email

Goal: Send three generated files in a single message. Chain: Three Convert to File nodes (distinct binary property names like report, raw, chart) → Merge → Gmail. Key setting: In the send node's attachments option, list the property names comma-separated: report,raw,chart. Gotcha: If two conversion nodes both write to data, one overwrites the other when the items merge, and an attachment quietly vanishes.

27. Base64 string to a real file

Goal: An API returns a file as a base64 text field; you need an actual attachment. Chain: HTTP Request → Convert to File. Key setting: Operation "Move Base64 String to File," pointed at the field holding the encoded string. Gotcha: Strip any data:application/pdf;base64, prefix first — the operation expects bare base64, and the prefix corrupts the output file.

Dedupe and state

Data Tables and other remembered state belong to Chapter 20; idempotency as a discipline is Chapter 24.

28. Never process the same record twice, ever

Goal: Cross-execution dedupe with no external storage. Chain: Fetch → Remove Duplicates → side effects. Key setting: Remove Duplicates, operation "Remove Items Processed in Previous Executions," keyed on a stable unique field. Gotcha: The seen-keys history lives inside your instance's database. Export the workflow to another instance, or rebuild the database, and the history is gone — everything looks new again.

29. Dedupe within a single run

Goal: Drop repeats inside one batch (a mailing list with the same email twice). Chain: Fetch → Remove Duplicates → continue. Key setting: Operation "Remove Items Repeated Within Current Input," comparing selected fields rather than whole items. Gotcha: Comparing whole items fails when records differ only by a timestamp field; always name the fields that define "same."

30. High-water mark in a Data Table

Goal: Fetch only records newer than the last successful run — no drift, no overlap. Chain: Schedule Trigger → Data Table (get the stored timestamp) → fetch with filter → process → Data Table (update the timestamp). Key expression: Filter the fetch with {{ $json.last_seen }} from the lookup, then advance the mark to the newest record's timestamp — not to $now. Gotcha: Updating the mark to $now loses records created between fetch and update. Always advance it to the maximum timestamp you actually processed.

31. A tiny counter with workflow static data

Goal: Count runs or rotate through options without any storage node. Chain: Any — the state lives in a Code node. Key expression: const s = $getWorkflowStaticData('global'); s.count = (s.count || 0) + 1; Gotcha: Static data persists only for production executions of an active workflow. Manual test runs read it but never save it — which looks like a bug until you know.

32. Idempotency ledger before side effects

Goal: Make "charge the card / send the email" safe to retry. Chain: Trigger → Data Table (get by operation key) → IF (already done?) → side effect → Data Table (insert the key). Key expression: Branch on whether the lookup returned a row; the key should identify the operation, e.g. {{ $json.orderId + ':welcome-email' }}. Gotcha: Insert the ledger row after the side effect succeeds, not before — otherwise a crash between insert and send marks work done that never happened. The full pattern is Chapter 24's.

33. Notify only when something changed

Goal: Watch a page or endpoint and alert on change, not on every check. Chain: Schedule Trigger → fetch → Code (hash the content) → Data Table (get stored hash) → IF (different?) → notify and update the hash. Key expression: In the Code node: const crypto = require('crypto'); crypto.createHash('sha256').update(content).digest('hex'). Gotcha: Hash only the part you care about. Pages with timestamps or rotating ads "change" every check; extract the target element first.

Watch out: Recipes 28, 30, 31, and 32 all keep state inside your n8n instance. That state is invisible on the canvas and is not part of the workflow's JSON export. Document where each workflow keeps its memory, and include the instance database in your backup story (Chapter 32).

Approval loops

Waiting mechanics are Chapter 9; the send-and-wait operations live on the messaging nodes themselves.

34. Slack approve/decline gate

Goal: Pause a workflow until a human clicks Approve or Decline in Slack. Chain: Work → Slack (Send and Wait for a Response, approval type) → IF → proceed or stop. Key expression: After resume, branch on {{ $json.data.approved }}. Gotcha: The paused run sits in a waiting state in the executions list (Chapter 21). If nobody ever clicks, it waits — set a wait-time limit (recipe 37) for anything time-sensitive.

35. Email approval that needs no n8n login

Goal: Let a manager approve from their inbox with one click. Chain: Work → Gmail (Send and Wait for a Response, with approval buttons) → IF → proceed. Key setting: The approval-type response option; the email carries hosted approve/decline links, and the approver needs no n8n account. Gotcha: Corporate link-scanning security tools sometimes "click" links in emails automatically. If approvals arrive suspiciously fast, switch to a double-confirmation form or a Slack gate.

36. Collect free-text input mid-workflow

Goal: Ask a human a question and use their typed answer downstream. Chain: Work → messaging node (Send and Wait, free-text or custom-form response) → continue with the reply in the item. Key expression: The reply arrives inside the resumed item's data field — inspect the node's output once rather than guessing the path. Gotcha: Whatever a human types is untrusted input. Validate it before feeding it into expressions or an AI prompt (Chapter 28's guardrails apply).

37. Approve within a deadline or escalate

Goal: Give the approver a fixed window, then route to a fallback. Chain: Slack (Send and Wait with "Limit Wait Time" enabled) → IF → approved path / escalation path. Key setting: The Limit Wait Time option on the send-and-wait operation. Gotcha: On timeout the run resumes without an approval recorded — your IF must treat "no answer" as its own case, not as a decline.

38. Auditable approvals

Goal: Keep a permanent record of who approved what, and when. Chain: Approval gate (recipe 34) → Data Table insert (approver, decision, timestamp, subject) → proceed. Key expression: Store {{ $now.toISO() }} alongside the decision fields. Gotcha: Execution logs are pruned over time on most setups, so the executions list is not an audit trail. The Data Table (or an external system) is.

Webhook handshakes and signature verification

Webhook theory — URLs, methods, response modes, test versus production — is Chapter 14.

39. Answer a URL-verification challenge

Goal: Pass the handshake some APIs (Slack-style) perform when you register a webhook. Chain: Webhook → IF (is this a challenge?) → Respond to Webhook. Key expression: Respond with {{ $json.body.challenge }}; set the Webhook node's Respond option to "Using 'Respond to Webhook' Node." Gotcha: The provider verifies the exact URL you registered. Register the production URL and make sure the workflow is active before you click verify, or the handshake times out.

40. Verify an HMAC-signed webhook

Goal: Reject any payload not signed with your shared secret. HMAC is a keyed hash: only someone holding the secret can produce a valid signature. Chain: Webhook (with the Raw Body option enabled) → Code → IF (valid?) → real work / respond with an error status. Key expression: In the Code node: const crypto = require('crypto'); const sig = crypto.createHmac('sha256', secret).update(rawBody).digest('hex'), compared against the signature header with crypto.timingSafeEqual. Gotcha: Compute the HMAC over the raw request body, byte for byte. Re-serializing parsed JSON almost matches — key order and whitespace differ — and "almost" fails verification forever. n8n Cloud already exposes the crypto module; a self-hosted instance may need to allow it with NODE_FUNCTION_ALLOW_BUILTIN=crypto (Chapter 32).

41. GitHub-style signature headers

Goal: Verify a webhook that sends sha256=<hex> in a signature header. Chain: Same as recipe 40. Key expression: Headers arrive lowercased in n8n, so read {{ $json.headers['x-hub-signature-256'] }} and strip the sha256= prefix before comparing. Gotcha: Comparing your bare hex digest against the prefixed header value fails every time, and the failure looks identical to a wrong secret.

42. Timestamped signatures and replay protection

Goal: Verify providers (Stripe-style) that sign a timestamp plus the body, so captured requests cannot be replayed later. Chain: Same shape as recipe 40, with an added freshness check. Key setting: Concatenate the timestamp and raw body exactly as the provider documents before hashing, and reject requests older than a few minutes. Gotcha: If the provider has a dedicated trigger node in the catalog, use it — it handles signing and replay windows for you, and recipe 40 becomes unnecessary.

43. Respond fast, work later

Goal: Acknowledge a webhook within the provider's timeout, then do slow work. Chain: Webhook → (heavy processing continues after the response). Key setting: Webhook node Respond option "Immediately," or place a Respond to Webhook node before the slow section. Gotcha: Providers that time out will retry the delivery, and now you have duplicates. Pair this recipe with dedupe on the event ID (recipe 28).

44. A simple shared-token gate

Goal: Keep casual traffic off an internal endpoint without full signature work. Chain: Webhook → real work. Key setting: Webhook node Authentication > Header Auth, backed by a credential holding the header name and secret value. Gotcha: This authenticates the caller but does not prove payload integrity; for money-moving or destructive endpoints, use recipe 40. Secrets handling is Chapter 34.

Watch out: Never let unverified webhook data trigger side effects. Anyone who discovers a production webhook URL can POST to it. Verification is the first thing after the trigger, and the failure branch responds with an error status and does nothing else.

Multi-channel notifications

Channel nodes come from the catalog (Chapter 12); branching mechanics are Chapter 9.

45. One event, every channel

Goal: Send the same alert to Slack, email, and a ticket system. Chain: Trigger → three parallel branches (Slack, Gmail, HTTP Request), all connected from the same output. Key setting: Multiple connections from one output create parallel branches — no special node needed. Gotcha: Branches run one after another, and by default an error in one stops the rest. Set Settings > On Error > Continue on each send node so one dead channel cannot silence the others.

46. Route by severity

Goal: Critical alerts page someone; warnings go to a channel; info goes to a digest. Chain: Trigger → Switch → per-severity branches. Key expression: Switch on {{ $json.severity }} with one rule per level. Gotcha: Enable the Switch node's fallback output. An unexpected severity value otherwise matches nothing, and the alert evaporates without a trace.

47. Quiet hours

Goal: Hold non-urgent notifications overnight and deliver at 8:00. Chain: Trigger → IF (urgent?) → the urgent path sends now; the other path → Wait → send. Key expression: Wait node in "At Specified Time" mode with {{ $now.hour >= 8 && $now.hour < 20 ? $now : ($now.hour >= 20 ? $today.plus({ days: 1 }).set({ hour: 8 }) : $today.set({ hour: 8 })) }} — deliver now during the day, else at the next 8:00. Gotcha: Each held notification is a paused execution. If overnight volume is high, buffer into a Data Table and flush with a morning digest (recipe 50) instead of parking hundreds of waiting runs.

48. Suppress repeat alerts

Goal: Alert on the first occurrence of a problem, not on all fifty repeats. Chain: Trigger → Data Table (get last-sent time for this alert key) → IF (older than an hour?) → send and update the timestamp. Key expression: {{ $json.last_sent < $now.minus({ hours: 1 }).toISO() }} — comparing ISO strings works because they sort chronologically. Gotcha: Choose the alert key carefully: key on the error type, not the full message, or unique timestamps in the text defeat suppression entirely.

49. Mention the person on call

Goal: Tag the right human per weekday. Chain: Alert chain → Slack, with a rotation expression inside the message. Key expression: {{ ['U0AAA','U0BBB','U0CCC','U0DDD','U0EEE'][$now.weekday - 1] ?? 'U0AAA' }} — Luxon, the date library behind $now, numbers weekdays 1 (Monday) to 7. Gotcha: Slack mentions need member IDs in the <@U0AAA> form, not display names. A hardcoded rotation also fails on holidays — for real on-call, read the schedule from a sheet or an API instead.

50. Buffer alerts, flush as a digest

Goal: Convert alert noise into one periodic summary. Chain: Workflow A: trigger → Data Table insert (one row per alert). Workflow B: Schedule Trigger → Data Table (get, then delete) → Aggregate → send (recipe 2). Key setting: Two separate workflows sharing one Data Table — the table is the handoff. Gotcha: Delete (or mark) rows as you flush them, in the same run. Fetch-without-clearing replays the same alerts in every digest.

AI micro-patterns

These are the smallest useful AI shapes. The cluster-node architecture is Chapter 26; single-call patterns are Chapter 27; agents and guardrails are Chapter 28.

51. Classify, then route

Goal: Sort incoming text (support emails, form fills) into named buckets and handle each differently. Chain: Trigger → Text Classifier (with a chat model attached) → one output branch per category. Key setting: Define each category with a one-sentence description — the descriptions are the classifier's real instructions. Gotcha: Configure the "when no clear match" behavior explicitly. The safe default is a fallback branch routed to a human, not silently discarding the item.

52. Extract free text into clean fields

Goal: Turn "we need 3 licenses by Friday, budget around 2k" into structured fields. Chain: Trigger → Information Extractor (with a chat model attached) → normal deterministic nodes. Key setting: Define each attribute with a name, a type, and a description; mark only truly mandatory attributes as required. Gotcha: Marking a field required pressures the model to produce something even when the text contains nothing — inviting invention. Prefer optional fields plus a downstream IF that routes incomplete extractions to a human.

53. Summarize for humans

Goal: Compress a long thread or document into three sentences for a notification. Chain: Source → Basic LLM Chain (with a chat model attached) → send. Key expression: A prompt with explicit shape: Summarize in exactly 3 bullet points for a busy operator. Include owner and deadline if present. Text: {{ $json.body_text }}. Gotcha: Unbounded prompts produce unbounded output. Constrain length and format in the prompt itself, and keep the model temperature low for consistency.

54. Cheap filter before expensive model

Goal: Stop paying model fees for items that obviously do not need AI. Chain: Trigger → IF (deterministic pre-filter) → AI branch / skip branch. Key expression: Something as plain as {{ $json.body_text.length > 200 }} or a keyword test — deterministic checks are free. Gotcha: Track how many items take each branch (Chapter 25). Pre-filters quietly rot as inputs change, and the failure mode is either paying for everything again or filtering out what matters.

55. Force structured JSON out of a model

Goal: Get output your downstream nodes can rely on, every time. Chain: Basic LLM Chain with "Require Specific Output Format" enabled → Structured Output Parser attached with your schema. Key setting: The output parser's schema — give an example object with the exact fields you expect. Gotcha: Even with a parser, treat parse failures as a real branch: enable the error output and route failures to a retry or a human. Never let unparsed model text flow into nodes that expect fields.

Tip: For classification and extraction (recipes 51 and 52), a small, inexpensive model is usually enough — save the frontier models for generation. Chapter 30 covers evaluating quality and controlling spend systematically.

Where to go when a recipe is not enough

Every recipe here is the short version of a longer idea. When one keeps failing in ways its gotcha does not explain, that is the signal to read the owning chapter: Chapter 13 for anything HTTP, Chapter 14 for anything webhook, Chapters 16 and 17 when expressions return the wrong thing, Chapters 23 and 24 when failures and duplicates creep in, and Chapters 26 through 30 when the AI patterns need guardrails. The two worked projects (Chapters 36 and 37) show many of these recipes composed into complete systems, and the Troubleshooting Encyclopedia (Chapter 39) is the companion shelf for the day something that used to work has stopped.

The Troubleshooting Encyclopedia

Something is broken and you want it fixed. This chapter is a symptom-first reference: find the section that matches where it hurts, find the entry that matches what you see, and work the causes in order. Every entry follows the same shape — Symptom (what you observe), Likely causes (ordered most to least probable, so you check the cheap ones first), Fix (what to do now), and Prevent (how to stop it recurring). The method of debugging — reading execution data, halving the workflow, pinning inputs — lives in Chapter 22 (The Debugging Craft); this chapter assumes it and gets straight to the answers. Where an entry needs deeper background, it points into Volumes C through G rather than repeating them.

One habit before you start: open the execution record first. The Executions list (Chapter 21, Executions: The System of Record) shows exactly which node failed, with what input and error text — far easier to match against the entries below than a vague sense that "it didn't work."

The Workflow Won't Trigger

Webhook URL returns 404

Symptom. You call your webhook URL and get a 404, often saying the webhook "is not registered."

Likely causes. (1) You are calling the production URL but the workflow is not active — the production webhook exists only while the activation toggle is on. (2) You are calling the test URL but the editor is not listening — the test URL is live only after you press the execute/listen button, and usually accepts a single call before switching off. (3) The HTTP method does not match: the node expects POST and you sent GET, or vice versa. (4) The path was edited after you shared the URL. (5) On self-hosted behind a reverse proxy, the advertised URL does not match what n8n registered because WEBHOOK_URL is unset or wrong.

Fix. Open the Webhook node, copy the exact URL from the Test URL / Production URL tabs, and confirm which one you are calling. Activate for production calls; press listen for test calls; align the HTTP method. On self-hosted, set WEBHOOK_URL to your public base URL and restart (Chapter 32, Self-Hosting from Zero).

Prevent. Treat the two URLs as different endpoints — they are. Chapter 14 (Webhooks In Depth) explains the test-versus-production model fully.

Webhook receives the call but the caller times out

Symptom. The sender reports a timeout or a 5xx, yet your execution log shows the workflow ran — sometimes even succeeded.

Likely causes. (1) The Webhook node's Respond option waits for the last node to finish, and your workflow takes longer than the caller will wait. (2) Respond is set to use a Respond to Webhook node, but on the path the execution took, that node is never reached (a branch skipped it, or an earlier node errored). (3) The workflow genuinely runs long, and nothing is wrong except the response strategy.

Fix. For anything slower than a second or two, set the Webhook node to respond immediately and do the work afterward. If the caller needs a computed answer, make sure every branch, including error paths, terminates in a Respond to Webhook node.

Prevent. Design webhooks as "acknowledge fast, work later" by default; Chapter 14 covers response modes and Chapter 24 (Reliability Patterns) covers the queue-and-process pattern.

Scheduled workflow never fires, or fires at the wrong time

Symptom. A Schedule Trigger workflow does nothing, or runs hours off from when you expected.

Likely causes. (1) The workflow is not active — schedules only run for active workflows. (2) Timezone mismatch: the schedule is interpreted in the workflow's timezone setting (which inherits the instance default), not your wall clock. (3) A cron expression — the compact schedule string that encodes "every Monday at 9" and the like — that does not mean what you think. (4) On self-hosted, the instance was down at the scheduled moment; missed schedules are not replayed. (5) In queue mode, the main (scheduler) process is unhealthy even though workers look fine (Chapter 33, Scaling and Performance).

Fix. Activate the workflow. Check the timezone in the workflow's settings and the instance default. Validate cron expressions with a cron explainer before trusting them. Check the Executions list for attempts versus true silence.

Prevent. Set the workflow timezone explicitly on every scheduled workflow, and add a cheap heartbeat — a scheduled run that posts to a channel — so silence becomes visible (Chapter 25, Monitoring, Insights, and Proving Value).

Tip: For any "won't trigger" mystery, the first binary question is: does an execution record exist? If yes, the trigger fired and your problem is downstream. If no, the problem is registration — activation state, URL, method, or schedule — and nothing inside the workflow matters yet.

Trigger fires twice, or fires in the wrong copy of the workflow

Symptom. Duplicate records, double messages, or a webhook that lands in an old version of your workflow.

Likely causes. (1) You duplicated a workflow and both copies are active with the same webhook path or polling trigger. (2) The upstream system retries because you responded slowly (see the timeout entry), so every slow run arrives twice. (3) Two environments (staging and production) both registered the same third-party trigger.

Fix. Deactivate the copy. Speed up webhook responses. Audit the third-party app's own webhook/subscription list and delete stale registrations.

Prevent. Make duplicated workflows inactive by default and give duplicates distinct webhook paths immediately. For retries you cannot prevent, make the workflow idempotent — safe to run twice with the same net effect as running it once; Chapter 24 shows the dedupe-key pattern.

Credential and OAuth Failures

OAuth connection fails during the consent screen

Symptom. You click "Connect," the provider's page opens, and you land on an error — commonly a redirect URI mismatch — instead of a granted connection.

Likely causes. (1) The OAuth Redirect URL shown in the n8n credential dialog was not pasted exactly into the provider's app configuration. (2) On self-hosted, n8n is advertising an internal address because the public base URL is not configured, so the redirect URL it generates is unreachable or unregistered. (3) The provider app is in a test mode that only allows whitelisted users. (4) Requested scopes are not enabled on the provider app.

Fix. Copy the redirect URL from the credential dialog character-for-character into the provider's app settings. On self-hosted, set the public URL configuration so the redirect URL is your real domain, then re-copy it — it will have changed. Add yourself as a test user or publish the provider app as required.

Prevent. Chapter 11 (Credentials from Zero) walks the full OAuth dance; do the redirect-URL step first, not last.

A credential that worked for weeks suddenly fails

Symptom. Executions start failing with 401 Unauthorized on a connection nobody touched.

Likely causes. (1) The refresh token expired or was revoked — providers commonly expire tokens for apps in testing mode, on password changes, or on security events. (2) Someone rotated the API key at the provider and forgot n8n. (3) The provider changed scope requirements or deprecated an auth method. (4) Your account or plan at the provider lapsed.

Fix. Open the credential and reconnect or re-enter the secret, then re-run one failed execution to confirm (Chapter 21 covers retrying from the Executions list).

Prevent. Move provider apps out of testing mode where possible, keep an inventory of which workflows use which credential (Chapter 34, Access, Security, and Secrets for Teams), and add an error workflow so auth failures page you instead of failing silently (Chapter 23).

"Credentials could not be decrypted"

Symptom. Every credential on the instance fails at once with a decryption error. Self-hosted only.

Likely causes. (1) The instance's encryption key changed — n8n encrypts credentials with a key kept in its config folder or in N8N_ENCRYPTION_KEY, and a recreated container without a persisted data volume generates a fresh key that cannot read old secrets. (2) You restored a database backup onto an instance with a different key. (3) In queue mode, a worker was started with a different key than the main instance, so only that worker's executions fail.

Fix. Recover the original key (from the old volume's config file or your secret store) and set it explicitly via the environment variable on every process. If the key is truly lost, the encrypted credentials are unrecoverable — delete and re-create them.

Prevent. Set the encryption key explicitly from day one, store it in a password manager, and treat "database backup plus key" as one inseparable backup unit (Chapter 32).

Watch out: Never "fix" a decryption error by wiping the data volume. The database is fine; only the key is wrong. Wiping converts a recoverable mistake into a total credential loss.

Keys are correct but calls still return 401 or 403

Symptom. You can use the same key successfully in another tool, but the n8n node is rejected.

Likely causes. (1) Wrong environment — a sandbox key against the production base URL or the reverse, especially with payment and CRM APIs. (2) Missing scopes for the specific operation the node performs. (3) The credential type expects the secret in a different field or header than you assumed (common with generic header-auth credentials on the HTTP Request node). (4) Stray whitespace pasted with the key.

Fix. Compare the node's generated request against a working call — Chapter 13 (The HTTP Request Node) shows how to inspect and hand-build the request. Align base URL, header name, and scopes; re-paste the key cleanly.

Prevent. Name credentials with their environment ("Stripe TEST", "Stripe LIVE") so the mismatch is visible at a glance.

Expression and Data-Shape Errors

"Cannot read properties of undefined" or [undefined] in output

Symptom. An expression like {{ $json.customer.email }} errors, or silently produces "undefined" in your output.

Likely causes. (1) The path is wrong for the data actually arriving — the field is nested, named, or capitalized differently than you typed. (2) The field exists on some items but not others, and one item without it breaks the run. (3) The upstream node changed shape — a different operation, an API update, or an edited Set node. (4) You are referencing the wrong node entirely.

Fix. Open the failing execution, look at the input of the failing node, and rebuild the path by clicking through the real data (dragging fields into the expression editor beats typing them). Guard optional fields with optional chaining — {{ $json.customer?.email }} — or filter out incomplete items first.

Prevent. Chapter 17 (Expressions) covers safe-path techniques; Chapter 16 (The Item Model in Practice) explains why "works on item 1, fails on item 7" is a data-shape question, not an expression question.

"Referenced node is unexecuted" or has no data

Symptom. An expression using $('Some Node') fails because that node never ran in this execution.

Likely causes. (1) The referenced node sits on a branch that was skipped this run. (2) You renamed the node and older expressions still point at the old name. (3) In manual testing you executed only part of the workflow, so upstream nodes have no data. (4) The reference crosses a boundary it cannot, such as into a different execution of a sub-workflow.

Fix. Reference a node that is on every path to the current one, or restructure so both branches merge before the data is needed (Chapter 9, Flow Control). After renames, search the workflow for the old name. In testing, run the whole workflow once so every node has data.

Prevent. Rename nodes early, before expressions accumulate, and prefer referencing the immediate input ($json) over distant nodes when you can.

The right value from the wrong item

Symptom. No error at all — but item 3's email gets item 1's name. The most dangerous bug in this chapter, because it ships.

Likely causes. (1) Using .first() (or an expression that resolves to the first item) inside a multi-item run, so every item reads item 1's value. (2) Item pairing was lost through a node that rebuilds items — some Code node patterns and aggregations discard the link between output items and their source, so $('Node').item can no longer trace back. (3) A Merge node combined lists by position when they were not actually aligned.

Fix. Use the paired-item form ($('Node').item.json.field) rather than .first() when you mean "this item's corresponding value." Where pairing is genuinely broken, carry the needed fields forward through the flow (add them in a Set node early) instead of reaching backward. For merges, join on an explicit key, not position.

Prevent. Test with three or more distinct items, never one — single-item tests cannot reveal pairing bugs. Chapter 16 is the deep treatment.

Comparisons and math behave wrongly (type coercion)

Symptom. An IF node sends "10" down the false branch of > 9, date comparisons scramble, or arithmetic concatenates instead of adding.

Likely causes. (1) The value is a string that looks like a number — webhook payloads, form data, and spreadsheet sources frequently deliver everything as text. (2) Strict type comparison is on and you are comparing a string to a number. (3) Dates as strings compared alphabetically, or mixed timezone formats. (4) Booleans arriving as the strings "true"/"false", which are both truthy.

Fix. Convert explicitly before comparing: {{ Number($json.qty) }}, {{ $json.flag === 'true' }}, or parse dates into date objects before comparing. Check the type-sensitivity option in the IF/Filter node and make it match your intent.

Prevent. Normalize types in one Set or Code node right after data enters the workflow, so everything downstream can trust the shapes. Chapter 18 (The Transformation Toolkit) covers conversion nodes.

Only one item gets processed

Symptom. Fifty items enter a node; one action happens.

Likely causes. (1) The node's "Execute Once" setting is enabled, so it deliberately runs only for the first item. (2) An upstream aggregation collapsed the list into a single item and you never noticed. (3) A loop construct is wired so the body runs but results never accumulate, or the "done" branch was connected where the "loop" branch belonged.

Fix. Check the node's settings tab for Execute Once. Inspect item counts on the connections in the executed view — the numbers on the wires tell you exactly where fifty became one. Re-wire loop branches per Chapter 9.

Prevent. Read the item counts after every test run; they are the cheapest diagnostic in the product.

Memory and Payload-Size Crashes

Execution dies on large data, or the instance restarts mid-run

Symptom. A workflow handling a big dataset fails with an out-of-memory crash, ends in an "unknown" or crashed state, or the editor becomes unresponsive; small test runs are fine.

Likely causes. (1) Too many items in memory at once — every node's full output stays in memory while the execution runs, so wide data times many nodes multiplies fast. (2) Binary files (PDFs, images, exports) processed in memory rather than streamed to disk. (3) A Code node that builds huge intermediate structures or duplicates the dataset. (4) The instance simply has too little RAM for the honest size of the job.

Fix. Process in slices: paginate at the source, use the batching/loop node to work in chunks, and split heavy phases into a sub-workflow called per chunk — a sub-workflow's memory is released when each call finishes (Chapter 9). On self-hosted, move binary data out of memory: a single instance can switch to filesystem mode (files go to disk, not RAM), but a queue-mode deployment must use shared external storage — object storage or the database — because a worker cannot read another process's local disk (Chapter 20, Files and Remembered State). Give the container more RAM as well. On n8n Cloud, memory scales with plan tier; either shrink the job or move up.

Prevent. Drop fields you do not need as early as possible — a Set node that keeps only three fields can cut memory by an order of magnitude — and design for chunks from the start when a source can grow.

Watch out: Out-of-memory crashes often leave no error message — the process died before it could write one. An execution stuck in "running" that never finishes, on a run involving large data, should be read as a memory suspect first.

"Request entity too large" or an oversized webhook payload is rejected

Symptom. Callers posting large bodies to your webhook get an HTTP 413 or a connection reset; smaller posts work.

Likely causes. (1) n8n's own payload size limit — a modest default cap on incoming request bodies, configurable on self-hosted. (2) A reverse proxy (nginx, Traefik, a load balancer) enforcing its own smaller body limit before n8n sees the request. (3) The sender attaching files inline that should be sent as links.

Fix. On self-hosted, raise the payload limit via its environment variable and raise the proxy's body-size limit too — both layers must agree. Better: have senders upload the file somewhere and post you a URL, then fetch it with the HTTP Request node.

Prevent. Pass references, not blobs, across webhooks whenever you control both ends (Chapter 14).

Stuck and Queued Executions

An execution shows "running" forever

Symptom. The Executions list shows a run that started hours ago and never ends.

Likely causes. (1) It is legitimately waiting — a Wait node, a "wait for webhook/approval" step, or a very slow external call; this is a feature. (2) The process crashed mid-run (often memory) and the record was orphaned in the running state. (3) An external API call is hanging with no timeout set. (4) An unbounded loop is genuinely still looping.

Fix. Open the execution and see which node it is sitting on. For waits, that is by design. For orphans, stop/delete the stale record. For hangs, set a timeout on the HTTP Request node and set a workflow-level execution timeout in the workflow settings so runaway runs are killed automatically.

Prevent. Give every workflow a sane execution timeout and every outbound call a request timeout; unbounded means "until something else breaks."

New executions pile up in a queued or waiting state

Symptom. Triggers fire, but executions sit queued and start late.

Likely causes. (1) A concurrency cap: instances limit how many production executions run at once (configurable self-hosted; plan-dependent on Cloud), and long-running workflows can occupy every slot. (2) One slow or stuck workflow is hogging capacity (see previous entry). (3) In queue mode, too few workers for the load, or workers down entirely. (4) A burst of triggers — a backfill, a retry storm — exceeding anything you sized for.

Fix. Find and fix the slot-hogs first; killing one stuck long-runner often drains the whole queue. Then raise concurrency or add workers if the load is real and sustained (Chapter 33). Pace bursty sources with batching and waits (Chapter 24).

Prevent. Keep individual executions short — offload slow phases to sub-workflows or split work into many small executions, which queue and scale far better than a few enormous ones.

Queue Mode, Workers, and Self-Hosting

Everything here applies to self-hosted instances; Cloud owners can skip to community nodes. Chapter 32 covers setup, Chapter 33 covers queue-mode architecture — this section is only what breaks.

Workers are idle while the queue grows

Symptom. Queue mode is on, executions queue endlessly, and worker logs show nothing happening.

Likely causes. (1) Workers cannot reach Redis — wrong host, port, password, or a network gap between containers; queue mode uses Redis as the hand-off between main and workers. (2) Main and workers point at different Redis instances or databases, so jobs are published where no one listens. (3) Workers point at a different application database than main, so they cannot load the workflows they are handed. (4) Version mismatch between main and worker images after a partial upgrade. (5) The worker process is not actually running in worker mode.

Fix. Read the worker logs first — connection errors name the culprit. Verify Redis host/credentials, database connection, and image versions are identical across main and workers; confirm the workers were started with the worker command. Restart workers after fixing.

Prevent. Deploy main and workers from one compose/manifest so their configuration cannot drift, and upgrade them together, never piecemeal.

Production webhooks or OAuth break behind a reverse proxy

Symptom. The editor works on your domain, but webhook URLs display an internal address, OAuth redirects go to localhost, or webhook calls to the public domain 404.

Likely causes. (1) The public base URL (WEBHOOK_URL) is not set, so n8n builds URLs from what it sees locally. (2) The proxy is not forwarding the standard proxy headers, so n8n misjudges protocol or host. (3) In scaled setups, dedicated webhook processor processes are not receiving the proxied traffic.

Fix. Set the public base URL environment variable to your real HTTPS domain and restart; confirm the Webhook node now displays the public address. Configure the proxy to pass host and forwarded-proto headers. Check the routing rules that send webhook paths to webhook processors in scaled deployments (Chapter 33).

Prevent. After any proxy or domain change, re-open a Webhook node and read the URL it displays — it tells you exactly what n8n believes about itself.

"Connection lost" banner in the editor

Symptom. The editor intermittently shows a lost-connection warning; manual executions seem to finish but the UI never updates.

Likely causes. (1) The reverse proxy is not passing websocket upgrade headers, so the editor's live push channel cannot stay open. (2) A proxy or load-balancer idle timeout shorter than the push connection's quiet periods. (3) Genuine instance restarts (check the memory entries above).

Fix. Enable websocket support/upgrade headers on the proxy and lengthen its idle timeout. If the banner coincides with restarts, chase the restart cause, not the banner.

Prevent. Use a proxy configuration known to work with n8n from the self-hosting docs rather than a hand-rolled one (Chapter 32).

The UI gets slower every week; the database balloons

Symptom. The Executions list crawls, backups swell, and eventually disk fills.

Likely causes. (1) Execution pruning is not enabled (or the retention window is enormous), so every execution's full data is kept forever. (2) Saving successful executions with large payloads when you only need failures. (3) Running production workloads on SQLite, which degrades under this growth pattern much sooner than Postgres.

Fix. Enable execution pruning with a retention period you can defend, and tune per-workflow save settings so routine successes stop hoarding data. For serious volume, migrate to Postgres (Chapter 32).

Prevent. Decide retention deliberately as part of go-live, not after the disk-full alert; Chapter 21 discusses what execution data is worth keeping.

Community Nodes and Upgrade Breakage

"Unrecognized node type" — a node shows as a question mark

Symptom. A workflow renders with an unknown-node placeholder and will not run, citing an unrecognized node type.

Likely causes. (1) The workflow uses a community node — a third-party node package installed separately (Chapter 15) — that is not installed on this instance; classic after migrating, restoring, or importing a workflow from elsewhere. (2) The community package failed to reinstall after an upgrade or on a fresh container without persisted node storage. (3) The package name changed or was unpublished upstream. (4) Rarely, a built-in node from a much newer n8n version imported into an older instance.

Fix. Install the missing package via Settings > Community Nodes (the error usually names the package). For containers, ensure the data volume persists installed packages, or bake required packages into your image. If the package is gone upstream, rebuild the step with built-in nodes — the HTTP Request node can usually replace an abandoned integration wrapper (Chapter 13).

Prevent. Keep a manifest of community packages per instance, and prefer built-in or verified nodes for anything business-critical.

Workflows misbehave after upgrading n8n

Symptom. After a version upgrade, some workflows error or behave differently, though nothing in them changed.

Likely causes. (1) A documented breaking change in the release notes — behavior defaults, environment variable renames, or node changes; major versions in particular remove deprecated behavior. (2) A community node incompatible with the new version. (3) The database migrated forward but you then tried to roll the application back, which older versions cannot read. (4) You skipped many versions at once, compounding several small changes into one confusing jump.

Fix. Read the release notes for every version you crossed and match symptoms to listed changes. Update community nodes. To roll back safely you need the pre-upgrade database backup — restore it and the old version together.

Prevent. Back up before every upgrade, upgrade regularly in small steps rather than rare giant leaps, and rehearse on a non-production instance if downtime hurts (Chapter 32). Existing workflows keep using the node versions they were built with — n8n versions node behavior internally — so most upgrades are quiet; the exceptions are exactly what release notes exist for.

Tip: After any upgrade, run a smoke test: execute two or three representative workflows manually and check one webhook and one schedule fired. Five minutes of smoke testing beats discovering breakage from a customer.

AI Failures

AI steps fail in their own characteristic ways. Background on the cluster-node architecture is in Chapter 26; agent mechanics in Chapter 28; retrieval pipelines in Chapter 29; cost and evaluation discipline in Chapter 30.

Context length exceeded

Symptom. The provider rejects a request because the prompt exceeds the model's context window — the maximum text it can consider at once.

Likely causes. (1) Chat memory has grown unbounded: an agent with a long-running session drags its whole history into every call. (2) Retrieval is stuffing too many (or too large) document chunks into the prompt. (3) You are inlining an entire file or dataset when the model only needs a slice or summary. (4) The chosen model simply has a small window for the job.

Fix. Cap memory with a windowed buffer (keep the last N exchanges) or summarize older history. Reduce the number of retrieved chunks and shrink chunk size at ingestion (Chapter 29). Pre-summarize large inputs in a cheap earlier step. If the task honestly needs huge context, pick a larger-window model.

Prevent. Log prompt sizes while building (Chapter 30's evaluation habits) — context overflows announce themselves in the size trend long before the hard failure.

The agent loops on tool calls or runs away

Symptom. An AI Agent node calls the same tool again and again, burns tokens, and finishes late, empty, or at its iteration cap.

Likely causes. (1) A tool's output does not tell the model whether it succeeded — an empty or ambiguous result reads as "try again." (2) Vague tool names and descriptions, so the model cannot decide which tool answers the question and thrashes. (3) The system message sets an impossible bar ("keep searching until certain"). (4) No iteration cap configured. (5) Overlapping tools that each look almost right.

Fix. Make every tool return an explicit, informative result — including a clear "no results found" — and rewrite tool descriptions to say precisely when to use each one. Set the agent's maximum iterations to a modest number. Tell the model in the system message to answer with what it has when tools come up empty.

Prevent. Test tools in isolation before handing them to an agent; a tool that confuses you will confuse the model more (Chapter 28).

RAG answers ignore your documents (empty retrievals)

Symptom. A retrieval-augmented workflow — one that looks up relevant passages from your own documents and feeds them to the model, the pattern known as RAG — answers from the model's general knowledge, admits it found nothing, or hallucinates, because the vector store (the database holding those passages as searchable numeric vectors) returned nothing useful.

Likely causes. (1) Ingestion never populated the store — the insert workflow failed silently or wrote zero chunks; check its executions. (2) Query and ingestion use different embedding models — the embedding model is what turns text into the numeric vectors a similarity search compares, and vectors from two different models are not comparable, so search returns noise or nothing. (3) Wrong index, collection, or namespace names between insert and query. (4) A similarity threshold or top-K (how many top matches to return) so strict that nothing passes. (5) Chunking that splits meaning badly, so no chunk matches a natural question.

Fix. Verify the store's document count directly. Pin the identical embedding model on both sides. Align index/namespace names exactly. Loosen the threshold and raise top-K until you see results, then tighten to taste. Re-chunk with sizes and overlap that keep ideas intact (Chapter 29).

Prevent. Build a one-question test — a query whose answer you know is in the documents — and run it after every ingestion change.

Provider rate limits and quota errors (429s)

Symptom. AI nodes fail with "too many requests," or with quota/billing errors that look similar but are not.

Likely causes. (1) A loop firing model calls as fast as items allow, tripping the provider's requests- or tokens-per-minute limits. (2) Several workflows sharing one API key, so combined load exceeds the limit even though each looks innocent. (3) A genuine quota or billing exhaustion — a distinct error meaning "add credit or raise the tier," which no retry will cure. (4) A new or low-tier provider account with tight limits.

Fix. Read the exact error: rate limit and quota exhaustion are different diseases. For rate limits, enable retry-on-fail with waits on the node, and pace loops with batching plus a Wait node between batches (Chapter 24). For quota, fix the account. For shared-key contention, split keys per workload or centralize calls in one paced sub-workflow.

Prevent. Chapter 30's cost-control patterns — budgets, batching, and caching repeated prompts — keep you comfortably under limits instead of skating along them.

The model's output breaks the next node

Symptom. The AI step "succeeds," but a downstream node fails parsing its output — expected JSON, got prose, markdown fences, or a half-finished structure.

Likely causes. (1) No structured-output enforcement, so the model returns conversational text around the data. (2) The output was truncated by a maximum-token limit and the JSON never closed. (3) The prompt shows no example of the exact shape you need. (4) A smaller model that follows format instructions unreliably.

Fix. Use the structured output parser (attach it to the model or agent, with a schema) so format is enforced rather than requested. Raise the response token limit if outputs truncate. Put a literal example of the desired output in the prompt. Add an error branch that catches parse failures and retries once (Chapter 23).

Prevent. Treat model output as untrusted input — validate its shape before anything irreversible consumes it, exactly as you would validate a webhook payload.

When the Entry Isn't Here

No encyclopedia is complete. When your symptom matches nothing above: reduce the workflow until the failure isolates (Chapter 22's halving method), read the failing node's raw input and error verbatim, and search that exact error text — the n8n community forum is dense with solved cases. If you built the failing piece from a worked project, Chapters 36 and 37 include their own project-specific pitfalls. And once you have fixed something painful, spend two minutes on prevention — an error workflow, a timeout, a heartbeat — because the cheapest troubleshooting session is the one the monitoring chapter (25) let you skip.

Mega-Glossary and the Resource Shelf

Every term this compendium has defined, gathered in one place, followed by the small set of external resources worth keeping within arm's reach. Nothing new is taught here. Each glossary entry gives a one-sentence plain-English definition and points to the chapter of record — the chapter where the term received its full treatment, with context, examples, and warnings. If a definition raises a question, the pointer is the answer.

The chapter closes with something a printed reference needs and rarely admits: instructions for aging. n8n moves quickly, and a book about it is a snapshot. The final section explains what typically changes between versions and how to re-verify any claim in these forty chapters after the product has moved on.

Tip: Use this glossary as a routing table, not a textbook. When a term in conversation, documentation, or a forum thread is unfamiliar, look it up here, get the one-sentence version, and follow the chapter pointer only if you need the mechanics.

The Mega-Glossary, A to W

The vocabulary runs from activation to workspace; conveniently, nothing in this glossary starts with X, Y, or Z. Cross-references between entries are marked with see. Where a term has two meanings — token is the classic offender — both senses get their own entry.

A

• Activation — flipping a workflow's switch to on, so its triggers fire on their own without anyone pressing a button. See Chapter 10.
• AI Agent node — the node that hands a language model a goal plus a set of tools and lets it decide which tools to call, in what order, until the goal is met. See Chapter 28.
• Always Output Data — a node setting that forces a node to emit one empty item instead of nothing, so downstream nodes still run when a lookup comes back empty. See Chapter 8.
• Annotation — a label or note attached to a saved execution so you can find and interpret that run later. See Chapter 21.
• API (application programming interface) — the structured, machine-readable doorway a service exposes so software can use it without clicking through the human interface. See Chapter 13.
• API key — a single secret string that both identifies you to a service and authorizes your requests. See Chapter 11.
• Aggregate node — combines many items into one, the mirror image of Split Out. See Chapter 18.
• Authentication — proving to a service that you are who you claim to be; the entire business of credentials. See Chapter 11.

B

• Backoff — waiting progressively longer between retry attempts so a struggling service gets room to recover. See Chapter 24.
• Base URL — the fixed front portion of an API's address, onto which individual endpoints are appended. See Chapter 13.
• Basic auth — the simple authentication scheme that sends a username and password with every request. See Chapter 11.
• Batching — processing items in bounded groups, usually with a pause between groups, to stay under rate limits. See Chapter 24.
• Binary data — file content (images, PDFs, spreadsheets, audio) carried alongside an item's JSON rather than inside it. See Chapter 20.
• Branch — one of several paths execution can take out of a node. See Chapter 9.

C

• Canvas — the visual editing surface where you place nodes and draw the connections between them. See Chapter 4.
• Chat model — the sub-node that supplies the actual language model an AI node calls; swap it to change providers without rebuilding the workflow. See Chapter 26.
• Chat Trigger — the trigger node that gives a workflow a chat interface, starting a run for each incoming message. See Chapter 28.
• Chunking — splitting documents into smaller passages so each can be embedded and retrieved on its own. See Chapter 29.
• CLI (command-line interface) — n8n's terminal commands for import, export, and instance chores. See Chapter 35.
• Cluster node — the architecture in which one root node (such as the AI Agent) is assembled from attached sub-nodes rather than standing alone. See Chapter 26.
• Code node — the node that runs your own script when clicks and expressions are not enough. See Chapter 19.
• Community edition — the free, self-hostable, fair-code-licensed version of n8n. See Chapter 2.
• Community node — an integration package built by someone outside the vendor, which you install yourself. See Chapter 15.
• Concurrency — how many executions an instance runs at the same time. See Chapter 33.
• Credential — a saved, encrypted login or secret that n8n uses on your behalf; created once, referenced by many nodes. See Chapter 11.
• Cron expression — the compact five-or-six-field syntax for describing a recurring schedule. See Chapter 7.

D

• Data pinning — freezing a node's output so that re-runs while building reuse the saved data instead of calling the live service again. See Chapter 10.
• Data table — n8n's built-in spreadsheet-like storage for small datasets that persist between executions. See Chapter 20.
• Database (instance database) — where an n8n instance stores its workflows, credentials, and execution history; production self-hosts use a real database server rather than the default file-based one. See Chapter 32.
• Deactivation — switching a live workflow off so its triggers stop firing. See Chapter 10.
• Deduplication — discarding items you have already processed, whether with the Remove Duplicates node or a stored record of what you have seen. See Chapter 24.
• Docker — the container technology that is the standard way to run self-hosted n8n. See Chapter 32.
• Dot notation — addressing nested fields with periods, as in customer.address.city. See Chapter 16.

E

• Edit Fields (Set) node — the workhorse node for renaming, adding, removing, and reshaping fields; formerly named simply Set. See Chapter 18.
• Editor — the browser application where you build, test, and manage workflows. See Chapter 4.
• Embed — n8n's licensed offering for building the workflow editor into your own product, so your customers automate without leaving your app. See Chapter 35.
• Embedding — a list of numbers representing the meaning of a piece of text, so that similar meanings sit near each other and can be searched. See Chapter 29.
• Encryption key — the secret an instance uses to encrypt stored credentials; lose it and every saved credential becomes unreadable. See Chapter 32.
• Endpoint — one specific URL path on an API, representing a particular resource or action. See Chapter 13.
• Enterprise edition — the paid, licensed tier of self-hosted n8n that unlocks team and governance features such as SSO, finer-grained roles, environments, and external secrets. See Chapter 2.
• Environment variable — a named setting supplied to a self-hosted instance at startup to configure its behavior. See Chapter 32.
• Environments — keeping separate development and production copies of your workflows and promoting changes between them, typically through the source control feature. See Chapter 35.
• Error branch — a second output path from a node that receives failures, letting the run continue instead of halting. See Chapter 23.
• Error Trigger — the node that starts an error workflow when some other workflow fails. See Chapter 23.
• Error workflow — a designated workflow that runs automatically when another workflow fails, usually to alert a human. See Chapter 23.
• Evaluation — scoring AI outputs against a fixed set of test cases so you know whether a prompt or model change actually helped. See Chapter 30.
• Execution — one complete run of a workflow, recorded along with the data every node produced. See Chapters 3 and 21.
• Execution list — the searchable history of runs: when each happened, whether it succeeded, and what data flowed through it. See Chapter 21.
• Expression — a double-curly-brace snippet that computes a value from earlier data at run time instead of using a fixed value. See Chapter 17.
• External secrets — pulling credentials from a dedicated vault product at run time rather than storing them inside n8n. See Chapter 34.

F

• Fallback — a backup path, service, or model that takes over when the primary one fails. See Chapter 24.
• Field — one named piece of data inside an item's JSON. See Chapter 16.
• Filter node — keeps only the items matching your conditions and discards the rest. See Chapter 18.
• Fixed/Expression toggle — the per-parameter switch between typing a literal value and computing one with an expression. See Chapter 8.

G

• Git — the version control system underlying n8n's source control feature. See Chapter 35.
• Guardrails — the constraints (system prompt, limited tools, output checks) that keep an AI agent inside its intended behavior. See Chapter 28.

H

• Header — a labeled line of metadata on an HTTP request or response, often carrying authentication. See Chapter 13.
• HTTP method — the verb of a request — GET to read, POST to create, and so on. See Chapter 13.
• HTTP Request node — the universal node that can call any API directly, even ones with no dedicated integration. See Chapter 13.
• HTTP status code — the three-digit result of a request: the 200s mean success, 400s mean you erred, 500s mean the server did. See Chapter 13.
• Human in the loop — pausing an automation until a person approves the next step. See Chapter 9.

I

• Idempotency — designing a workflow so that running it twice has the same effect as running it once. See Chapter 24.
• IF node — routes each item down a true branch or a false branch based on conditions. See Chapter 9.
• Insights — the built-in dashboard summarizing executions, failure rates, and time saved across the instance. See Chapter 25.
• Instance — one installed, running copy of n8n, with its own database, workflows, users, and settings. See Chapter 2.
• Integration — a ready-made connection to a specific product, delivered as one or more nodes. See Chapter 12.
• Item — the fundamental parcel of data that flows between nodes; nodes run once per item unless told otherwise. See Chapters 3 and 16.
• Item linking (paired items) — the bookkeeping that records which input item produced which output item, which is what lets expressions look backward accurately. See Chapter 16.

J

• JavaScript — the programming language of expressions and the default language of the Code node. See Chapter 19.
• JSON (JavaScript Object Notation) — the bracketed text format in which nearly all workflow data travels. See Chapter 3.

L

• LLM (large language model) — the text-in, text-out AI engine behind chat models and agents. See Chapter 26.
• Log streaming — pushing execution events to an outside logging or monitoring system as they happen. See Chapter 25.
• Loop — repeating part of a workflow, either implicitly (nodes run per item) or explicitly with looping nodes. See Chapter 9.
• Loop Over Items node — processes items in fixed-size chunks, one batch per pass; formerly named Split in Batches. See Chapter 9.
• Luxon — the date-and-time library that expressions use for parsing, formatting, and arithmetic on dates. See Chapter 17.

M

• MCP (Model Context Protocol) — an open standard that lets AI clients discover and call tools; n8n can both consume MCP servers and expose workflows as one. See Chapter 30.
• Memory (AI) — the sub-node that lets a conversation retain what was said earlier, so the model is not an amnesiac. See Chapter 28.
• Merge node — combines two branches back into one stream, by position, by matching key, or by simple append. See Chapter 9.
• Model — the specific AI engine (and version) you choose for a call; the choice drives quality, speed, and cost. See Chapter 26.
• Monitoring — watching workflow health over time and being told when something breaks, rather than checking run by run. See Chapter 25.
• Multi-main — running more than one main process for high availability in queue mode. See Chapter 33.

N

• n8n API (public REST API) — programmatic control of the instance itself: creating workflows, reading executions, managing credentials. See Chapter 35.
• n8n Cloud — the hosted, subscription version of n8n run by the vendor. See Chapters 2 and 31.
• Node — one block on the canvas performing one step of work; the atom a workflow is built from. See Chapter 3.
• Node details view — the panel that opens when you open a node: input on one side, parameters in the middle, output on the other. See Chapter 8.
• npm — the JavaScript package registry where community nodes are published. See Chapter 15.

O

• OAuth2 — the redirect-and-consent authorization dance that grants an app scoped access to your account without ever sharing your password. See Chapter 11.
• On-error setting — the per-node choice of what a failure does: stop the workflow, continue regardless, or route down the error output. See Chapter 23.
• Operation — the specific action chosen within a node's resource, such as send on a message. See Chapter 12.
• Output parser — the sub-node that forces a model's reply into a defined structure instead of free prose. See Chapter 27.

P

• Pagination — fetching a long list from an API in successive pages rather than one giant response. See Chapter 13.
• Paired items — see Item linking.
• Parameter — one configurable setting on a node. See Chapter 8.
• Partial execution — running a workflow only up to a selected node while you build, instead of the whole thing. See Chapter 10.
• Payload — the body of data a request or webhook carries. See Chapter 14.
• Polling — checking a service on a schedule to ask whether anything changed, as opposed to being pushed a webhook. See Chapter 7.
• Project — a grouping of workflows and credentials with its own membership and roles, used to give teams separate spaces. See Chapter 34.
• Prompt — the instruction text you send a model. See Chapter 27.
• Python — the second language option in the Code node. See Chapter 19.

Q

• Query parameter — a key-and-value option appended to a URL after the question mark. See Chapter 13.
• Queue mode — the scaling architecture in which a main process hands executions to worker processes through a Redis queue. See Chapter 33.

R

• RAG (retrieval-augmented generation) — fetching relevant passages from your own knowledge and inserting them into the prompt, so the model answers from your documents rather than its general training. See Chapter 29.
• Rate limit — a service's cap on how many requests you may make in a time window. See Chapter 24.
• RBAC (role-based access control) — assigning capabilities through roles such as owner, admin, and member rather than person by person. See Chapter 34.
• Redis — the in-memory data store that carries the job queue in queue mode. See Chapter 33.
• Remove Duplicates node — drops items that repeat earlier items, within a run or across runs. See Chapter 18.
• Resource — the kind of thing a node acts on — a contact, a message, a row. See Chapter 12.
• Resource locator — the picker that lets you identify a specific record by choosing from a list, pasting a URL, or entering an ID. See Chapter 12.
• Retry — automatically attempting a failed operation again, whether per node with Retry On Fail or per run from the execution list. See Chapter 23.
• Root node — the main node of a cluster — the AI Agent, for instance — to which sub-nodes attach. See Chapter 26.

S

• Schedule Trigger — starts a workflow at times you define, from "every five minutes" to a full cron expression. See Chapter 7.
• Schema view — the output display mode that shows field structure as a draggable tree. See Chapter 16.
• Scope — the specific permissions an OAuth grant covers, and no more. See Chapter 11.
• Self-hosting — running n8n on infrastructure you control. See Chapter 32.
• Session — one continuing conversation thread that AI memory tracks, keyed by an identifier. See Chapter 28.
• Set node — see Edit Fields (Set) node.
• Source control — connecting an instance to a Git repository so workflows are versioned and can be promoted between environments. See Chapter 35.
• Split in Batches — the former name of the Loop Over Items node; you will still meet it in older templates and forum threads. See Chapter 9.
• Split Out node — turns a list inside one item into many separate items. See Chapter 18.
• SSO (single sign-on) — logging in through a central corporate identity provider; generally a higher-tier feature. See Chapter 34.
• Static data (workflow static data) — a small piece of JSON a workflow can persist between its own executions. See Chapter 20.
• Sticky note — a canvas annotation for humans; it changes nothing at run time. See Chapter 10.
• Stop and Error node — deliberately fails a workflow with a message you write, so bad states fail loudly. See Chapter 23.
• Sub-node — a supporting node (model, memory, tool) that plugs into a root node instead of sitting in the main flow. See Chapter 26.
• Sub-workflow — a workflow invoked by another workflow, like a function call; the caller waits for its result. See Chapter 9.
• Switch node — routes items down one of several branches according to rules, where the IF node offers only two. See Chapter 9.
• System prompt — standing instructions that shape every reply a model gives in a conversation. See Chapter 27.

T

• Table view — the output display mode that shows items as rows and columns. See Chapter 16.
• Tag — a label on a workflow used for filtering the workflow list. See Chapter 10.
• Task runner — a separated process that executes Code node scripts outside the main process, for safety and performance. See Chapter 33.
• Temperature — the model setting that trades predictability for variety in output. See Chapter 27.
• Template — a shareable, importable pre-built workflow used as a starting point. See Chapter 6.
• Token (AI) — the word-fragment unit that language models read, count, and bill by. See Chapter 26.
• Token (authentication) — a secret string, often time-limited, sent with requests to prove authorization. See Chapter 11.
• Tool (agent) — a capability an AI agent may choose to invoke: a node, a sub-workflow, or an external function. See Chapter 28.
• Trigger — the node that starts a workflow when its event occurs; every workflow needs at least one. See Chapter 7.

U

• User management — inviting people to an instance and assigning their roles. See Chapter 34.

V

• Variable — an instance-level named value (reached in expressions through $vars) reusable across workflows, typically paired with environments. See Chapter 35.
• Vector store — a database that stores embeddings and finds the nearest-in-meaning matches to a query. See Chapter 29.
• Version history — saved prior versions of a workflow that you can inspect and restore. See Chapter 10.

W

• Wait node — pauses an execution until a time passes, a date arrives, or an external call resumes it. See Chapter 9.
• Webhook — an HTTP call one system makes to another the moment an event happens, pushing the news instead of waiting to be asked. See Chapter 14.
• Webhook node — gives a workflow its own URL so outside systems can start it by calling in. See Chapter 14.
• Webhook test and production URLs — the two addresses every Webhook node has: one that works while you listen in the editor, one that is served continuously once the workflow is active. See Chapter 14.
• Worker — a process that consumes executions off the queue in queue mode. See Chapter 33.
• Workflow — the whole automation: triggers, nodes, connections, and settings, saved as a single JSON document. See Chapter 3.
• Workspace — everything in the n8n application that is not the canvas: the overview, the workflow and credential lists, executions, and settings. See Chapter 4.

Watch out: Several nodes have been renamed over the product's life — Set became Edit Fields, Split in Batches became Loop Over Items — and older templates, screenshots, and forum answers use the old names freely. If a tutorial references a node you cannot find, suspect a rename before you suspect a missing feature.

The Resource Shelf

Beyond this book, a handful of resources cover almost every situation. Here is the shelf, with guidance on when to reach for each.

The official documentation

The docs at docs.n8n.io are the ground truth for the current version, and they divide into a few territories worth knowing by name: user documentation (workflows, the editor, data), the integrations library (a reference page for every built-in node and credential type), hosting documentation (everything self-hosted, from environment variables to scaling), the code and expressions reference, and the API reference. When this book and the docs disagree, the docs are describing a newer version — trust them for specifics and this book for the mental model. The node reference pages are the single most frequent destination: whenever a node's options do not match what a chapter described, the node's own docs page shows the current truth.

The community forum

The forum at community.n8n.io is where practitioners and the vendor's own staff answer questions, and its archive is deep enough that most problems you hit have been hit before. Reach for it in two modes. Search mode first: most error messages, node quirks, and "why does it do that" mysteries already have an answered thread. Post mode second: when search fails, a well-formed question — what you expected, what happened, and a minimal workflow that reproduces it — usually gets a useful answer. Unofficial spaces (a subreddit, assorted chat servers) exist and can be lively, but the forum is where answers are most likely to be correct and current.

Tip: Search the forum with the exact text of your error message in quotes. When posting, always state your n8n version, whether you run Cloud or self-hosted, and paste the smallest workflow JSON that shows the problem — the first reply to a vague post is always a request for exactly those three things.

The template library

The template gallery at n8n.io/workflows — also browsable from inside the editor — holds thousands of community-submitted workflows, searchable by app and use case. Chapter 6 (Choosing What to Automate and Three Ways to Start) treated templates as one of the three ways to start, and that remains the right frame: a template is a sketch to adapt, not a product to install. Expect to replace credentials, re-map fields to your data, and prune steps you do not need. Templates are also an underrated reading library — studying how an experienced builder structured error handling or looping teaches patterns faster than prose.

Release notes and version cadence

n8n releases at a brisk pace — new minor versions have historically arrived about weekly, with patch releases in between — so the release notes are not an occasional read but a working tool. The official docs maintain a release notes section listing what changed in each version, and the GitHub repository carries the same in release form, along with a dedicated list of breaking changes for self-hosters. n8n Cloud instances are updated for you on the vendor's schedule (Chapter 31 covers how much control you have over timing); self-hosted instances update only when you choose, which makes reading the notes before upgrading entirely your job.

Watch out: Self-hosters — never upgrade blind. Before moving versions, read the breaking-changes list for every version you are crossing, back up your database and your encryption key, and upgrade a staging instance first if you have one. Chapter 32 (Self-Hosting from Zero) covers the mechanics; the discipline is what matters.

Courses and certification

The official docs include structured text courses at beginner and intermediate levels, each building a real workflow step by step; n8n also runs a dedicated learning academy, and the vendor's video channel carries course-style playlists for people who learn better by watching. These are worth their time in two situations: onboarding a colleague who needs guided practice rather than a reference (this compendium is a reference), and filling gaps after you have learned n8n haphazardly on the job. A beginner certification with a quiz and a certificate of completion has been offered through the academy; treat any certificate as a pleasant signal rather than a credential the market demands, and check the current course pages for exactly what is on offer, since the specifics change.

Community node registries

When the built-in catalog lacks your integration, community nodes fill the gap, and there are two places to look. The npm registry is the canonical home — community nodes are published there as packages, discoverable by a shared naming convention and keyword. Inside the product, the nodes panel and community nodes settings surface installable packages, and n8n maintains a vetted "verified" subset — marked with a shield and manually reviewed for quality and security — that can be installed directly from the editor, including on Cloud. Chapter 15 (Community Nodes and Building Your Own) covers the installation mechanics and — more importantly — the vetting checklist.

Watch out: An npm package is code someone else wrote running inside your instance with access to whatever your instance can reach. Popularity is not vetting. Before installing any community node, apply Chapter 15's checklist: check maintenance recency, download counts, open issues, and ideally skim the source. On instances holding production credentials, be conservative.

The source repository

n8n's source lives in the n8n organization on GitHub under a fair-code license. You will rarely need it as an operator, but three uses come up: reading a node's source when its documentation is ambiguous (the code is the final authority on behavior), searching issues to learn whether a bug you hit is known and whether a fix has shipped, and filing an issue when you have found something genuinely new. Feature requests generally get more traction on the forum's dedicated section than in the issue tracker.

Tracking a Fast-Moving Product

This book was accurate when written. n8n will not hold still for it. Rather than pretend otherwise, here is what actually drifts, how fast, and how to re-verify a claim after the product moves.

What typically changes between versions

Different layers of the product drift at very different speeds, and knowing which layer a claim lives in tells you how much to trust it after an upgrade.

Two structural facts soften the churn. First, n8n versions its nodes internally: a workflow keeps behaving the way its nodes behaved when you added them, so new behavior applies only to newly added nodes and your existing workflows are far more stable than the changelog suggests. Second, the core data model has been stable for years; little in Volume D is likely to be wrong next year. The fastest-moving territory by a wide margin is Volume F — AI is where the vendor invests hardest, so read Chapters 26 through 30 as a snapshot of a moving frontier: the architecture (cluster nodes, tools, memory, RAG) is stable, the specific node roster is not.

How to re-verify this book's claims after an upgrade

When you suspect a chapter has drifted, run this sequence — it takes minutes, not hours.

First, classify the claim by the table above. A claim about the item model needs no re-verification; a claim about which plan includes SSO always does.

Second, read the release notes forward from roughly the version you last knew. Renames, removals, and new features are all announced there; five minutes of skimming usually resolves the question outright.

Third, check the node's or feature's documentation page, which always describes the current version. If the docs match the book, nothing changed. If they differ, the docs win.

Fourth, when documentation is ambiguous, test it. Behavior questions — does this setting still do that, does this expression still resolve — are settled empirically in a scratch workflow faster than by any amount of reading.

Tip: Keep a small probe workflow in your instance — a manual trigger, a few nodes exercising the behaviors you rely on most, pinned test data — and run it after every upgrade. Green output in thirty seconds tells you more than an evening with the changelog, and when something does break, you find out in your probe rather than in production.

Finally, when a UI path in this book no longer exists, do not conclude the feature is gone. Features move far more often than they die. Search the docs for the feature's name, check the workspace and instance settings areas, and only then check the release notes for a removal notice.

That is the contract of this chapter, and of the compendium: the mental model in these forty chapters is the durable part — workflows made of nodes, data flowing as items, executions as the record, credentials held once and referenced everywhere, errors as first-class citizens, AI as just another node with guardrails around it. Details will drift; the shelf above tells you where the current truth lives. Everything else is looking things up, and now you know where.