Messages vanishing after a reconnect: the Telegram conflict fix that stops losing your queue

You are out of the house, so you message the Hermes box at home: “re-run that backup script.” No read receipt, no reply. Two minutes later you send it again. Still nothing. You get home, open the log, and find a few 409 Conflict lines and then business as usual — except those two messages will never be processed.
This is the old Long Polling problem: two processes compete for the same bot’s getUpdates, Telegram lets exactly one win, and the other gets a 409. Hermes already retried. The problem was what it did while retrying.
Three different failures that all look like “the network”
Telegram-side failures sound alike and behave nothing alike. There are three paths, and each needs a different fix:
- Conflict (409): another poller holds this bot’s
getUpdatessession. Usually two gateways on one machine, an old process that never exited, or two machines configured with the same bot token. - Transient errors (a 502 and friends): one
getUpdatescall failed. - A “healthy” poll that never delivers: every round trip reports success, and queued messages still never arrive.
The batch merged on November 9 (PR #150983, plus #151077) touches all three. Start with the conflict, because that is where the damage was.
What a 409 used to cost: the queue
Conflict recovery restarted polling with drop_pending_updates=True.
That parameter is easy to misread. It does not end the other poller’s session — it tells Telegram to throw away every update sitting in the server-side queue. So messages you sent during those few dozen seconds were cleared on recovery. No error, no log line, no retry. Simply gone.
The retry counter was worse. Conflict recovery has a five-attempt ladder that logs (1/5), (2/5), and so on. In a live probe, three separate conflicts all logged (1/5): the ladder never climbed. Two causes, both in the same place. The recovery marker was cleared in a finally block as soon as start_polling() returned, before PTB’s background getUpdates made any progress. And during a 409 storm, getUpdates occasionally succeeds between conflicts, which reset the count to one. The design — “keep retrying for as long as the conflict lasts” — never actually ran.
Today: the queue survives, and the ladder climbs
The before/after is concrete. Same scenario in both runs: a competing poller produces three 409s, with one direct message queued during each conflict.
| Scenario | Before | After |
|---|---|---|
| Three 409s, one DM queued during each | log shows (1/5) three times, four deleteWebhook(drop_pending_updates=true) calls, DM 1 never answered |
(1/5) → (2/5) → (3/5), only the cold-boot drop, all three DMs answered |
Two changes:
- Conflict recovery now restarts with
drop_pending_updates=False, matching the network-error ladder. A cold boot still clears the queue; a conflict no longer does. - When a conflict episode ends is now governed by a 120-second quiet period (
_POLLING_CONFLICT_QUIET_PERIOD = 120.0). That is longer than any gap inside a single storm, so an occasional successfulgetUpdatesno longer resets the count to1/5.
In other words: the old path was “see a 409, reset, wipe the queue.” The new path is “treat this as one ongoing episode, keep the queue, and back off step by step.” The docs now say it plainly: conflict recovery preserves the queue, and messages sent during a 409 are delivered once polling resumes.
A 502 is not a fatal error
The second path is transient errors. One 502 Bad Gateway used to make recovery wait out a 15-second deadline, then log updater.stop() did not finish before the network-recovery deadline, then escalate the whole thing to Fatal telegram adapter error and rebuild the adapter from scratch. A half-second blip cost a full rebuild.
Now the same Updater is restarted in about a second: no fatal line, no deadline line, and the next DM is answered normally.
“Healthy” polls: 186 seconds down to 125
The third path is the sneakiest. getUpdates keeps succeeding, but queued messages are never handed over — the network layer looks perfect. A heartbeat probe watches for this: two consecutive probes that see “updates queued but not consumed” and it declares the poll stuck and restarts it.
Before, the gap from message arrival to restart was 186 seconds. Now it is 125, and it fits inside a single awake window. On a laptop that dozes, that difference is practical: the old timer could be interrupted by sleep and never accumulate two consecutive probes.
Cold boot is a separate decision
Conflict recovery now keeps the queue, but a cold boot still drops it by default. That is deliberate: for an always-on server, a restart means “clean up,” and the backlog is treated as stale.
If your host is a laptop that shuts down overnight, messages sent while it was off sit in Telegram’s Bot API queue and get discarded at the next boot — silently, with no log line. To receive that backlog in order:
platforms:
telegram:
extra:
drop_pending_on_cold_boot: false
There is a cost. After a crash, a preserved queue can redeliver an update the crashed instance had partially processed. Telegram’s offset usually prevents it, but time-sensitive commands sent during a long outage will run at boot. That trade-off is yours to make.
The quieter bug: unhandled updates were being receipted
One more fix in this batch (PR #151077) has a subtler symptom. Some update types Hermes does not handle — a 🎲 dice message, for instance — were quietly marked “done.” That receipt told Telegram the update had been delivered, so it stopped redelivering, and nothing appeared in the log.
Now an update that no handler claims is not receipted, and it logs one INFO line with field names only, never content:
Update 1000 matched no core handler; not receipted (fields: message(chat,date,dice,from,message_id), update_id)
The same PR fixes a shutdown edge: stopping the adapter could finish before its handled-update records were released. Now it waits for those releases, and a coroutine cancelled while waiting its turn is closed instead of leaking.
Two things you can do yourself
First, make sure two processes are not fighting over one bot. hermes gateway list shows every profile with whether its gateway is running and the pid, which is exactly how you spot a duplicate. If you run several profiles with their own bots, hermes gateway migrate --dry-run runs a preflight that reports duplicate bot tokens — the most common source of 409s.
hermes gateway list
hermes gateway migrate --dry-run
Second, stop reading 409 as “Telegram is flaky.” It is almost always local configuration: one token used twice. Removing the duplicate does more than any timeout tweak.
When you can use this
PRs #150983 and #151077 both merged to main on November 9, 2026. v0.23.0 shipped on November 6, so these fixes are not in v0.23.0; they arrive with the next stable release.
Update (2026-11-10): these changes shipped in v0.23.1 (November 9) —
hermes updateis enough. The “not in v0.23.0” statements above are still accurate; v0.23.1 closes the gap.
If you are losing messages right now, there are two stopgaps: kill the duplicate gateway (the real fix), and set drop_pending_on_cold_boot: false so restarts stop swallowing the backlog — bearing in mind the redelivery caveat above.
For the other half of the reliability picture — how Hermes decides a gateway has gone quiet — see silent disconnects and the heartbeat. For the interaction-side Telegram setup (inline buttons, pickers), see this guide.
The short version
Three failure paths, three failure modes: a conflict wipes the queue (messages lost outright), a transient error gets treated as fatal (full adapter rebuild), a healthy-looking poll is caught too late (three minutes). The fixes keep the queue and climb the ladder, reuse the Updater, and cut detection to under two minutes. All of it is main-only today, but for anyone running Hermes on Telegram, this is the answer to “did my message actually get lost?”