@awesomate/hosting-mcp/skill/awesomate-n8n/references/error-handling.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# Error handling — every production workflow needs a plan

A workflow with no error plan fails silently: the run turns red in a list
nobody looks at, and the user finds out days later when a customer asks why
they never got a reply. Before you call any build "done", it needs one of
two things (both is better):

1. **A per-node error plan** — retry/fallback on the nodes that can fail.
2. **An error workflow** — a separate workflow that runs whenever THIS one
   fails and notifies the OWNER.

**Errors route to the client, never to Awesomate.** The notification target
is always the user's own email/Slack/inbox — they own the automation, they
get told when it breaks. Never wire a notification to an Awesomate address.

## 1. Per-node error plans

Every node has error settings (in the workflow JSON, on the node object):

- `retryOnFail: true` + `maxTries` (2–3) + `waitBetweenTries` (ms) — for
  anything that can fail transiently: HTTP calls, email sends, API nodes.
- `onError: 'continueErrorOutput'` — gives the node a second (error) output
  you can route to a fallback branch (log the failure to a data table, send
  an apology, use a default value). Use when the workflow should keep going.
- `onError: 'stopWorkflow'` (the default) — right when continuing would do
  damage (don't charge a card after the lookup failed).

Rule of thumb from the build loop: **every external call has an error plan.**
An HTTP Request with no retry and no error branch is a design gap, not a
style choice.

## 2. The error workflow (`settings.errorWorkflow`)

n8n lets any workflow name another workflow as its **error workflow**: when a
run fails, n8n executes that workflow with the failure details. The link
lives in the workflow's settings:

```json
{ "settings": { "errorWorkflow": "<workflow id of the error handler>" } }
```

**To check whether a workflow has one:** `awesomate_n8n_workflows` with the
id and `detail: 'full'` — look at `settings.errorWorkflow`. Empty/absent =
failures go nowhere.

**Agency-deployed workflows may already have an error handler wired** (the
bundle installs one that alerts the user). Don't replace or repoint it — it
outranks anything you'd build for that slot. Check what the existing handler
does before adding your own.

## 3. Building a simple notify-me error workflow

Two nodes:

1. **Error Trigger** (`n8n-nodes-base.errorTrigger`) — no parameters; it
   fires when any workflow that names this one as its errorWorkflow fails.
   Its output includes the failed workflow's name/id, the execution id and
   URL, and the error message + node.
2. **Send Email** (reuse their existing email credential from the inventory)
   — to the USER's address, subject like
   `[Automation failed] {{ $json.workflow.name }}`, body with the error
   message, the node that failed, and the execution URL so they can open it.

Build it through the normal loop (SKILL.md §3, through the n8n MCP server),
then set `settings.errorWorkflow` on each production workflow with the n8n
server's update tool and republish each one. One error workflow can serve
every workflow on the instance: build it once, point everything at it.

Test it honestly: you can't fake a failure with a test fire
without breaking something, so tell the user what will happen ("if any of
these fail, you'll get an email like this") and verify the error workflow
itself runs by executing it against a sample payload where possible.

## 4. AI error analysis (`awesomate_n8n_findings`)

On Pro/Embedded with the "AI error analysis" privacy toggle on, Awesomate's
platform already analyzes their failures. `awesomate_n8n_findings` returns
those findings for their account — `clientSummary` (plain-language
explanation), `needsClientAction` (something only they can do, like
reconnecting a credential), and `fixReady` (a fix exists). It is read-only:
use it to explain and prioritise, not as a substitute for your own diagnosis
of the execution data. On a 403, the plan or the toggle is the reason —
`awesomate_privacy_settings` (hosting skill) tells you which; the user flips
toggles themselves under **n8n → Settings → Privacy** at
hub.awesomate.ai/settings?tab=privacy — the one for this tool is labelled
**"Enable AI Error Diagnosis"**.

## 5. What to do when you inherit a workflow with no plan

When diagnosing a failure (SKILL.md §5) on a workflow with no error plan,
say so in one line after the fix: "this workflow has no failure alert — want
me to add one so you hear about the next one from your inbox instead of from
a customer?" Once per session, not on every workflow.