n8n-nodes-workflow-load-balancer

An n8n community node that routes each incoming item to one of several target workflows, with automatic failover, retries, and a circuit breaker — so you don't hand-build IF + Error Trigger chains.

What it does

Drop the node between a trigger and a set of target workflows. For each item it picks a target by the chosen routing mode, runs it via executeWorkflow, and on failure/timeout automatically retries then fails over to the next target. First success wins and flows out the success output. If every target fails, the failure strategy decides what happens.

Outputs: success (0) and allFailed (1). Each item carries a __lb metadata object (correlation id, winner, which targets it failed over from) unless you turn it off.

Routing modes

| Works from in-process signals | Notes | |---|---| | Round Robin, Weighted, Priority, Random | no signals needed | | Least Running | tracks concurrent runs in this node process | | Latency, Health Score | EWMA of past executions in this process | | Sticky Session | same key → same target (5-min affinity) | | Least Queue / CPU / Memory | fall back to the fallback mode + flag __lb.fallbackUsed |

Why the last row falls back: a community node runs inside execute() and cannot read Redis/BullMQ queue depth or per-worker CPU/RAM — those are n8n platform internals. The node degrades honestly instead of faking a signal. The full distributed design (Redis-shared state, worker heartbeats, dashboard, REST APIs) is in TRD-Workflow-Load-Balancer.md; it requires a core/Enterprise fork, not a community node.

Reliability

• Retry per target with none / fixed / exponential+jitter backoff.
• Circuit breaker per target: opens after N consecutive failures, half-opens after a cooldown, closes after successful probes. State is per node process (ponytail: global lock — back with Redis for multi-worker sharing).
• Failure strategy when all targets fail: error (throws) · deadLetter (route item to a DLQ workflow, continue) · fallbackPayload (emit a static payload, continue).

Scope / honest limits

• Failover is at-least-once. If a target had side effects before failing, they aren't rolled back — make targets idempotent using the injected __lb.correlationId.
• Breaker/affinity/round-robin state is per process (see above).
• Streaming targets aren't failed over mid-stream.

Develop

npm install
npm test          # runnable router self-check (no framework)
npm run build     # compiles to dist/ + copies icon

Then link into your n8n install per the community node docs (~/.n8n/custom or npm link).

Layout

• nodes/WorkflowLoadBalancer/router.ts — pure routing/failover/breaker logic (no n8n imports, unit-tested).
• nodes/WorkflowLoadBalancer/WorkflowLoadBalancer.node.ts — n8n node; wires the router to executeWorkflow.
• nodes/WorkflowLoadBalancer/router.test.ts — 8-invariant self-check.