@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.


## "Could not create the draft" / writes fail while reads work

If reads, `awesomate_n8n_context` and `validate` all succeed but every WRITE
(create draft, activate, promote, test-fire) fails, the cause is almost always
the account's stored n8n API key — not the hub, not Cloudflare, not the
workflow JSON. Validation runs on Awesomate's side and never touches the
instance, which is exactly why it keeps passing.

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. Recreate/move the table into the workflow's project (`awesomate_n8n_datatable_write`, Support Plus+). 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 | Activate via `awesomate_n8n_deploy`. Never activate a copy — `promote` preserves webhookIds |
| 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 | `awesomate_n8n_deploy {action: "activate"}` (new) or `promote` (replacing a live one). E2E-verify: activate + 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 (the hub enforces it); add `executionTimeout` to every loop workflow; bound rows per run |
| `429 quota_exceeded` | Plan daily cap reached | STOP immediately. Do not retry-loop — tell the user the cap is hit; it resets daily or they upgrade. Limits are in `awesomate_n8n_context` |

## Verification after a fix

- Re-run realistically: `awesomate_n8n_test {workflowId, payload}` for manual
  runs; for live paths, activate + POST the production webhook + 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 (`update_draft`, `promote`, `rollback`, `test`,
  datatable writes): 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.
- `429 quota_exceeded` — never burn remaining quota on retries.
- Fix requires the FFMPEG variant or a higher plan — explain the gate; the
  upgrade happens in the hub, not here.