Description

n8n-nodes-fallback-chat-model

Community node “Fallback Chat Model” for n8n. It attaches to the
AI Agent node (“Chat Model” input) just like the built-in
OpenAI/Anthropic/Mistral chat model nodes.

Below it, you can connect 2 to 10 arbitrary chat model nodes
(e.g. local llama.cpp/Ollama, then OpenAI, then Anthropic, …).
When a model fails (timeout, rate limit, connection error, HTTP 5xx, …),
the next model in the connected order is tried automatically.
Tool/function calling is preserved (important for the AI Agent), because
internally a real BaseChatModel class is used instead of a simple
.withFallbacks() chain.

How it works

[llama.cpp Chat Model] ─┐
[OpenAI Chat Model]     ─┼─► [Fallback Chat Model] ─► [AI Agent]
[Anthropic Chat Model]  ─┘

• Input 1 = primary model (required)
• Inputs 2–10 = fallback models, in the displayed order
• The node parameter “Number of Models” controls how many inputs are shown
• Optional Timeout (Seconds): if a model takes longer than X seconds to

respond (for streaming: until the first token), the request is aborted
and the next model takes over. 0 = disabled.

• Optional Random Order: shuffles the model order on every run instead

of using the connection order — handy as simple load balancing across
providers. The fallback chain still applies on failures.

• Optional Final Model (Last Resort): adds an extra input for a model

that is ONLY used when all regular models have failed. It always stays
last in the chain — even with Random Order or Reverse Order enabled.
Typical use: a reliable paid API as the guaranteed backstop behind a
chain of local/cheap models. By default the final model is exempt from
the timeout (“Final Model Ignores Timeout”), so the last resort always
gets the chance to finish.

• On failure, a warning is logged (can be disabled) and the next model

is tried automatically

• On startup, the actual fallback order is written to the n8n log

(Fallback order: 1. ..., 2. ...) so you can verify it

• If your n8n version delivers the models in reverse order, enable the

“Reverse Order” toggle in the node

Known limitations:

• If a model fails mid-stream (after tokens were already emitted), we

cannot seamlessly switch to another model in the middle of an answer.
The fallback reliably covers failures before or at the start of the
response (connection errors, auth errors, rate limits, timeouts), which
is the main use case.

• Intentional aborts (stop button in n8n, timeout signals) are propagated

immediately and do not trigger the fallback chain.

Installation (self-hosted n8n)

Via the n8n UI: Settings → Community Nodes → Install a community node
and enter:

n8n-nodes-fallback-chat-model

Note: unverified community nodes require a self-hosted n8n instance;
they are not available on n8n Cloud.

Manual installation (without npm registry)

For a quick local setup without publishing to npm, mount the built package
into your n8n Docker container:

1. On the server: create a folder for custom nodes (if it doesn't exist)
mkdir -p ~/n8n-custom-nodes
2. Copy this package directory there, e.g.
scp -r n8n-nodes-fallback-chat-model user@server:~/n8n-custom-nodes/
3. Build once on the server (if you don't copy dist/ along)
cd ~/n8n-custom-nodes/n8n-nodes-fallback-chat-model
npm install --ignore-scripts
npm run build

Then add to your n8n docker-compose service:

services:
  n8n:
    # ... your existing configuration ...
    environment:
      - N8NCUSTOMEXTENSIONS=/home/node/.n8n/custom-nodes
    volumes:
      - ~/n8n-custom-nodes/n8n-nodes-fallback-chat-model:/home/node/.n8n/custom-nodes/n8n-nodes-fallback-chat-model:ro

Restart the container:

docker compose up -d --force-recreate n8n

The node “Fallback Chat Model” should then appear in the node search
under AI → Language Models.

Development

npm install --ignore-scripts
npm run build      # build once
npm run dev        # tsc --watch

Note: --ignore-scripts skips the native build of isolated-vm (a
transitive dev dependency of n8n-workflow that is only needed for
n8n’s code node sandbox, not for this package). This avoids build
failures on very recent Node.js versions.

Releasing a new version

Publishing runs automatically via GitHub Actions (with npm provenance,
as required by n8n for verified nodes). One-time setup: add an npm
granular access token as the NPM_TOKEN repository secret (see comments
in .github/workflows/publish.yml). Then, for each release:

npm version patch        # bumps version, creates commit + tag (v0.1.x)
git push --follow-tags   # pushing the tag triggers the publish workflow

Changelog

• 0.1.6 – Added “Final Model Ignores Timeout” option (default: on):

the last-resort model is exempt from the configured timeout — better
slow than no answer at all

• 0.1.5 – Added optional “Final Model (Last Resort)” input: a dedicated

model that is only used when all regular models failed, always kept at
the end of the chain regardless of Random/Reverse Order

• 0.1.4 – Added per-model timeout (aborts slow models and hands the

task to the next one, with a Promise.race safety net for models that
ignore abort signals; user aborts still propagate immediately) and an
optional random model order for simple load balancing

• 0.1.3 – All descriptions, log messages, and docs translated to English
• 0.1.2 – Fixed model ordering (n8n returns connections in reverse

order / as bulk arrays depending on version), added deduplication,
“Reverse Order” toggle, and startup logging of the active order

• 0.1.1 – Fixed lost failure logging after bindTools(), added abort

detection (stop button/timeouts no longer trigger the fallback chain),
added streaming support with pre-first-chunk fallback

• 0.1.0 – Initial release