From fcf87b611d339f74facc85a57abd1de98e8d3b09 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Mon, 9 Feb 2026 11:32:59 -0500 Subject: [PATCH] docs: add n8n workflow JSON pitfalls to CLAUDE.md conventions Adds 4 lessons learned from Phase 16 hotfix to prevent repeat issues: - Connection keys/targets must use node names, not IDs - Unraid GraphQL nodes must use Header Auth credential - Node names must be unique - Use $('Node Name') after GraphQL chains, not $input.item.json Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 1d274bf..5a6345b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -201,3 +201,7 @@ unraid-api apikey --create \ staticData._errorLog = JSON.stringify(errorLog); ``` - **Keyword Router rule ordering**: `startsWith` rules (e.g., `/debug`, `/errors`) must come BEFORE generic `contains` rules (e.g., `status`, `start`), otherwise `/debug status` matches `contains "status"` first. Connection array indices must match rule indices, with fallback as the last slot. +- **Connection JSON keys must be node NAMES, not IDs**: n8n resolves connections by matching keys to node `name` fields. Using node `id` values as connection keys creates silently broken wiring. Same rule for target `"node"` values inside connection arrays. +- **Unraid GraphQL HTTP nodes must use Header Auth credential**: Do NOT use `$env.UNRAID_API_KEY` as a manual header — causes `Invalid CSRF token` errors. Correct config: `"authentication": "genericCredentialType"`, `"genericAuthType": "httpHeaderAuth"`, with `"credentials": { "httpHeaderAuth": { "id": "unraid-api-key-credential-id", "name": "Unraid API Key" } }`. Copy auth config from existing working nodes. +- **Node names must be unique**: Duplicate names cause ambiguous connections. n8n cannot distinguish which node a connection refers to. +- **After GraphQL query chains** (HTTP → Normalizer → Registry Update), `$input.item.json` is a container object from the chain, NOT upstream preparation data. Use `$('Upstream Node Name').item.json` to reference data from before the chain.