luckberg/unraid-docker-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add n8n workflow JSON pitfalls to CLAUDE.md conventions

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Lucas Berger
2026-02-09 11:32:59 -05:00
parent d5bc0be2fe
commit fcf87b611d
1 changed files with 4 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+4
View File
@@ -201,3 +201,7 @@ unraid-api apikey --create \
staticData._errorLog = JSON.stringify(errorLog); 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. - **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.