From b65f6ca7fe0ab59055702a7ad5cd7d8eb94582f6 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Mon, 20 Apr 2026 12:29:22 -0700
Subject: [PATCH] fix(telegram): actionable error for DM topics when Topics
 mode not enabled (#13162)

When createForumTopic fails with 'not a forum' in a private chat,
the error now tells the user exactly what to do: enable Topics in
the DM chat settings from the Telegram app.

Also adds a Prerequisites callout to the docs explaining this
client-side requirement before the config section.
---
 gateway/platforms/telegram.py                 |  7 +++++++
 website/docs/user-guide/messaging/telegram.md | 10 ++++++++++
 2 files changed, 17 insertions(+)

diff --git a/gateway/platforms/telegram.py b/gateway/platforms/telegram.py
index e849a03c7..01bcf4da9 100644
--- a/gateway/platforms/telegram.py
+++ b/gateway/platforms/telegram.py
@@ -496,6 +496,13 @@ class TelegramAdapter(BasePlatformAdapter):
                     "[%s] DM topic '%s' already exists in chat %s (will be mapped from incoming messages)",
                     self.name, name, chat_id,
                 )
+            elif "not a forum" in error_text or "forums_disabled" in error_text:
+                logger.warning(
+                    "[%s] Cannot create DM topic '%s' in chat %s: Topics mode is not enabled. "
+                    "The user must open the DM with this bot in Telegram, tap the bot name "
+                    "at the top, and enable 'Topics' in chat settings before topics can be created.",
+                    self.name, name, chat_id,
+                )
             else:
                 logger.warning(
                     "[%s] Failed to create DM topic '%s' in chat %s: %s",
diff --git a/website/docs/user-guide/messaging/telegram.md b/website/docs/user-guide/messaging/telegram.md
index a92fc8d22..dbdfc3f4a 100644
--- a/website/docs/user-guide/messaging/telegram.md
+++ b/website/docs/user-guide/messaging/telegram.md
@@ -325,6 +325,16 @@ Each topic gets its own conversation session, history, and context — completel
 
 ### Configuration
 
+:::caution Prerequisites
+Before adding topics to your config, the user must **enable Topics mode** in the DM chat with the bot:
+
+1. Open your private chat with the Hermes bot in Telegram
+2. Tap the bot's name at the top to open chat info
+3. Enable **Topics** (the toggle to turn the chat into a forum)
+
+Without this, Hermes will log `The chat is not a forum` on startup and skip topic creation. This is a Telegram client-side setting — the bot cannot enable it programmatically.
+:::
+
 Add topics under `platforms.telegram.extra.dm_topics` in `~/.hermes/config.yaml`:
 
 ```yaml