@awesomate/hosting-mcp/skill/awesomate-n8n/references/troubleshooting.md

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

# Troubleshooting — diagnosing a failing workflow

Diagnosis playbook. Work the flow top-to-bottom; do not jump to fixes before
you have the failing execution's detail.


## Template installs or activation fail while reads work

If reads and `awesomate_n8n_context` succeed but every hub WRITE (a template
`install`, `activate` or `test` through `awesomate_n8n_library`) fails, the
cause is almost always the account's stored n8n API key: not the hub, not
Cloudflare, not the template. Workflows you write through the n8n MCP server
use its own MCP key, not this one, so a refusal there is the n8n server's own
answer; read it as such.

The server says so explicitly: HTTP **409** with `code: n8n_credential_invalid`.
Older builds reported this as a 502, which reads like an outage — if you see a
bare 502 on writes only, suspect the key before you suspect the platform.

**Tell the user to do this, in this order:**

1. Open their n8n (the response's `instanceUrl`, e.g. `https://<slug>.awesomate.io`)
   → **Settings → n8n API** → **Create an API key**. Copy it.
2. Open **https://hub.awesomate.ai/n8n/settings** → paste it into
   **"New n8n API Key"** → save. The status chip should go from
   *Key rejected* to *Connected*.
3. Retry the action.

Do not retry before they confirm the new key is saved, and do not go probing
hub or Cloudflare status — a genuine hub problem breaks reads too.

Common causes: the key was revoked or regenerated in n8n, or the instance was
rebuilt (a rebuilt instance shows 0 workflows and invalidates every old key).

## Diagnosis flow

1. `awesomate_n8n_context` — confirm consent flags, capabilities, and the
   instance fingerprint before reading anything else.
2. `awesomate_n8n_executions {workflowId}` — list recent runs. Pick the
   failing execution (or the first failure in a streak — later failures are
   often downstream noise from the same cause).
3. `awesomate_n8n_executions {executionId}` — detail: error message, the node
   that threw, last node executed.
4. **Walk the item data BACKWARDS from the failing node.** The node that
   throws is rarely the node that is wrong — the usual cause is an upstream
   node emitting a mis-mapped or missing field that a downstream expression
   consumes. Compare what each upstream node emitted against what the failing
   node's expressions expect. Read the node config with
   `awesomate_n8n_workflows {id, detail:'full'}`.
5. `awesomate_n8n_executions {executionId, debug: true}` — node-level output
   data. Requires `error_content_analysis` consent:
   - `403 consent_required` → give the user the `settingsUrl` from the error
     response and stop; they enable it under **Settings → Privacy** at
     `hub.awesomate.ai/settings?tab=privacy` (old `/n8n/settings?section=privacy`
     links redirect there).
   - `tooLarge: true` → payload over 15MB. Use the summary in the response;
     do NOT retry hoping for the full payload.
6. Node behaving strangely rather than erroring → check its schema with
   `awesomate_n8n_node_docs {tool: "get_node"}` (on `503
   node_catalog_unavailable`, fall back to the `vendor/` references).

## Common errors → cause → fix

| Error / symptom | Likely cause | Fix |
|---|---|---|
| Downstream fields empty/undefined on a webhook workflow | Webhook data lives at `$json.body`, not `$json` | Use `{{ $json.body.field }}`. #1 cause of "undefined" in webhook flows |
| "access to environment variables is denied" | `$env` is blocked fleet-wide — in Code nodes AND regular field expressions | Use `{{ $vars.key \|\| 'fallback' }}` or a Config Set-node literal; never `$env` |
| "$helpers is not defined" (works in editor preview, fails at run time) | Task runners strip `$helpers` from Code nodes | Move HTTP calls to HTTP Request nodes; process results in a downstream Code node |
| "Could not find the data table: '<id>'" | PROJECT scope, not existence: datatables resolve within the workflow's own project at runtime | Check which project owns the table (`awesomate_n8n_inspect {what: "datatables"}`) vs the workflow. The user recreates the table inside the workflow's project (n8n's Data tables). Reference tables by name, never by id |
| Credential "could not be found" | Sharing/RBAC — the credential exists but is not shared with the workflow's project/owner. Almost never deletion | Verify it exists via `awesomate_n8n_inspect {what: "credentials"}`; user shares it to the project in the n8n editor |
| Webhook URL returns 404 | Workflow not active: production webhook paths register only while active. Test URLs work only while the editor is listening | Publish it through the n8n MCP server (or the user switches it on in n8n). Never activate a copy: change the live one on its own id (SKILL.md §4) |
| Form URL 404s at its custom path | formTrigger ignores the custom `path`; forms serve only at `/form/<webhookId>` | Use a webhook trigger when a stable path matters |
| "Unrecognized node type" / unknown node at activation | Community media node on an instance without the FFMPEG variant (Support Plus+ gate) | Check `awesomate_n8n_context` capabilities; upgrade variant or rebuild on core nodes. Note: static validation flagging `CUSTOM.*` nodes "unknown" is a false positive — trust activation, not the validator |
| Output shows literal "[object Object]" | Expression resolves to an object where a string is expected | Drill to the scalar (`{{ $json.body.user.email }}`) or wrap in `JSON.stringify()` |
| Workflow saved but never executes | Draft was never activated/published; saving is not publishing | Publish it through the n8n MCP server (a new workflow), or republish the live one after updating it. E2E-verify: publish + hit the production webhook + poll executions |
| Code node output vanishes or breaks downstream | Not returning `[{ json: {...} }]`, or leftover template boilerplate | Return an array of `{json}` objects; check whether the node is unedited boilerplate |
| Node config valid yesterday, "Invalid value for 'operation'" today | Partial update stripped the `operation` discriminator | Set `resource` + `operation` together in the same update; re-validate |
| `crashed` status, hours-long runtime, loop workflow | `saveExecutionProgress: true` (quadratic writes, 2TB WAL incident) and/or no `executionTimeout` on a `splitInBatches` loop | Keep `saveExecutionProgress` FALSE (set it yourself; nothing enforces it for you); add `executionTimeout` to every loop workflow; bound rows per run |

## Verification after a fix

- Re-run realistically: the n8n MCP server's execute tool, a POST to the
  production webhook, or the user's own trigger; then poll
  `awesomate_n8n_executions` until the new run appears.
- Inspect the fixed run's data, not just its status — an `onError: continue`
  branch can turn a failure into a "successful" run carrying an `error` key.

## When to STOP and hand off

- **`agency_managed` error**: the workflow is managed by Awesomate. Reads
  are fine: list it, read executions, run `debug`, and explain the failure to
  the user freely. Switching it off or on is allowed when the user asks (the
  reply carries `built_by_us`; tell them what stops while it's off). Do NOT
  attempt any other change (editing it through the n8n MCP server, test
  fires, data table changes): those go through Awesomate support.
  Summarize your diagnosis so the user can paste it into their ticket.
- `403 consent_required` the user declines to enable — diagnose from the
  execution summary only; say plainly what deeper access would show.
- Fix requires the FFMPEG variant or a higher plan — explain the gate; the
  upgrade happens in the hub, not here.