Breaking: this release requires Node.js >= 22.19. That is the only change — no new nodes, no changed
options, no flow migration.
Do I have to do anything?
Run node -v.
- v22.19 or newer — nothing to do. Upgrade normally.
- older — upgrade Node first, then this package. npm otherwise refuses the install with
EBADENGINE,
which is deliberate: it is better than a package that fails at runtime.
If you run Node-RED 5, you are already fine — Node-RED 5 itself requires Node >= 22.9. The group that
has to act is Node-RED 4 on Node 20.
Why
The old engines: { node: ">=20.0.0" } promised a configuration our own host runtime rules out:
node-red@5 declares >=22.9, so a supported Node-RED 5 install cannot be on Node 20. Keeping that claim
alive cost a CI leg and acted as a veto over dependency upgrades, in exchange for protecting a combination
npm already refuses to install. Node 20 also reached end of life on 2026-04-30 and receives no further
security fixes.
The floor is 22.19 rather than 22.9 so that a future HTTP-stack upgrade will not need a second major
release.
Full reasoning: ADR 0010.
What did not change
The HTTP stack stays on undici 7. The undici 8 bump was investigated and rejected: undici v8 removed
the legacy dispatcher handler wrappers, while Node's built-in fetch — which is what carries our
per-bot dispatcher, including SOCKS proxy support — still drives a dispatcher through them. A v8
dispatcher is accepted but never returns a response. This is independent of the Node version and will
change only once Node itself bundles undici 8. See
ADR 0011.
Rollback
npm install node-red-contrib-telegrambot@18.1.1 then node-red-restart. V18.1.1 is identical apart from
the >=20 floor.
Details in CHANGELOG.md
and MIGRATION.md.