From 564b6aa2aae0101266c8cad2765b80788ebb331f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 15 Jan 2026 07:23:19 +0000 Subject: [PATCH] docs: clarify Telegram IPv6 DNS troubleshooting --- docs/channels/telegram.md | 5 +++++ docs/channels/troubleshooting.md | 3 +++ 2 files changed, 8 insertions(+) diff --git a/docs/channels/telegram.md b/docs/channels/telegram.md index e74f220dd..7cd6c45ea 100644 --- a/docs/channels/telegram.md +++ b/docs/channels/telegram.md @@ -324,6 +324,11 @@ Outbound Telegram API calls retry on transient network/429 errors with exponenti - Make sure your Telegram user ID is authorized (via pairing or `channels.telegram.allowFrom`) - Commands require authorization even in groups with `groupPolicy: "open"` +**Bot starts, then silently stops responding (or logs `HttpError: Network request ... failed`):** +- Some hosts resolve `api.telegram.org` to IPv6 first. If your server does not have working IPv6 egress, grammY can get stuck on IPv6-only requests. +- Fix by enabling IPv6 egress **or** forcing IPv4 resolution for `api.telegram.org` (for example, add an `/etc/hosts` entry using the IPv4 A record, or prefer IPv4 in your OS DNS stack), then restart the gateway. +- Quick check: `dig +short api.telegram.org A` and `dig +short api.telegram.org AAAA` to confirm what DNS returns. + ## Configuration reference (Telegram) Full configuration: [Configuration](/gateway/configuration) diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index d40a92af2..6eed5265d 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -19,3 +19,6 @@ clawdbot channels status --probe - Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting) - Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting) - WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick) + +## Telegram quick fixes +- Logs show `HttpError: Network request for 'sendMessage' failed` or `sendChatAction` → check IPv6 DNS. If `api.telegram.org` resolves to IPv6 first and the host lacks IPv6 egress, force IPv4 or enable IPv6. See [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting).