workflow-load-balancer-ha

n8n community node that routes executions across target workflows with automatic failover, retries and a circuit breaker

Package Information

Released: 3 mo ago
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0

Available Nodes

Documentation generating…

Workflow Load Balancer icon
Workflow Load Balancer
Route executions across target workflows with automatic failover, retries and a circuit breaker
Respond to Workflow Balancer icon
Respond to Workflow Balancer
Send the response of a primary/backup workflow back to the Workflow Load Balancer

Documentation

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.

Discussion