Telegram "can't parse entities": why your agent's bot fails
Telegram's 400 "can't parse entities" means the bot's Markdown or HTML broke its rules: an unescaped character or unclosed tag. What the byte offset means.
Telegram’s formatting parser could not read the markup in the text your bot sent. The bot asked for MarkdownV2, HTML or legacy Markdown, and the text broke that format’s rules: a reserved character such as . or - left unescaped, a tag with no end tag, or a tag Telegram does not support. The bot token and the network are fine. For an agent, update it where a release fixes the case you hit; for your own bot, escape the text as Telegram’s docs say, send the formatting as entities instead of a parse mode, or send plain text. The byte offset is where the parser gave up, counted in bytes of the UTF-8 text.
What the message means
When a bot sends a message with parse_mode set, Telegram turns the markup into formatting before delivering it. If that parse fails, the whole send is refused with a 400, and nothing reaches the chat. The text after “can’t parse entities:” names what went wrong. These are the forms the parser in TDLib, Telegram’s open-source library, produces:
Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 58
Bad Request: can't parse entities: Character '.' is reserved and must be escaped with the preceding '\'
Bad Request: can't parse entities: Can't find end of a URL at byte offset 25
Bad Request: can't parse entities: Unsupported start tag "br" at byte offset 120
Bad Request: can't parse entities: Can't find end tag corresponding to start tag "b"CopiedThe first comes from legacy Markdown; the reserved-character and URL forms, and “Can’t find end of” followed by an entity’s type, come from MarkdownV2; the tag forms, along with unclosed, unexpected and unmatched tags, come from HTML. So the wording also tells you which parse mode the bot used. The numbers and names above are examples.
Why an AI agent’s replies hit it
A model writes ordinary Markdown and prose, and Telegram’s formats are stricter than either.
MarkdownV2 reserves eighteen characters. Per the Bot API docs, outside an entity every one of these must carry a backslash:
_ * [ ] ( ) ~ ` > # + - = | { } . !CopiedA sentence ending in a full stop, a hyphenated word, a numbered list or a version number in parentheses is enough. Inside code and pre, only ` and \ need escaping, and inside a link’s address only ) and \. A **bold** that a model opens and never closes gives “Can’t find end of … entity”.
HTML accepts only the tags Telegram lists (<b>, <i>, <code>, <pre>, <a>, <blockquote> and a few more), and every <, > and & that is not part of a tag must be written <, >, &. Named entities other than those and " are refused; numeric ones are fine. So a reply that explains HTML and mentions <b> in prose has a start tag with no end tag, and a <br> is an unsupported tag.
Legacy Markdown is kept only for backward compatibility, and its weak spot is the underscore: a snake_case name or a file path with one _ opens an italic that never closes. Users of home-automation bots report exactly this with entity names.
What the byte offset tells you
The number is a position in the text as Telegram received it, after any escaping the bot did, counted in bytes of UTF-8: in TDLib’s parser it is the index it was reading in the string when it began the entity, URL or tag it could not finish. For the “Can’t find end” forms it points at where the unclosed thing starts, not where the text ended. An emoji is four bytes and most accented or Cyrillic letters two, so counting characters in an editor lands in the wrong place once the text has any. To see the spot, slice the exact text the bot sent:
raw = text.encode("utf-8")
n = 58 # the offset from the error
print(raw[max(0, n - 20):n + 20].decode("utf-8", "replace"))CopiedThis is a different unit from the one the entities field uses: there, offset and length are UTF-16 code units. Mixing the two is a common way for hand-built entities to be off by a few characters. The HTML error about a missing end tag carries no offset; it names the tag instead, so search the text for it.
If your agent is OpenClaw
OpenClaw sends Telegram replies as HTML by default, built by its own formatter from the model’s Markdown and from any HTML the reply carries. A recent report found a case that formatter let through: a reply that mentions a start tag like <b> in prose. The report, filed on November 9, 2026 against the 2026.11.1 code, describes Telegram refusing it with “Can’t find end tag corresponding to start tag” and OpenClaw then sending the reply as plain text, losing all its formatting and the tag itself.
The fix, merged the same day, escapes a start tag still open at the end of the text, so it shows as written and the rest keeps its formatting. It is in the beta 2026.11.10-beta.1 and not in 2026.11.6, the current stable release, whose branch was cut before it; the rich messages page of the docs already describes the fixed behaviour. By the report’s account the cost before the fix is formatting on the odd reply, not a lost message, so the next stable release that carries the fix is the update to take. If a reply is refused in some other way, the error text above tells you which rule it broke, and that is what to put in a report to OpenClaw.
If your agent is Hermes
Hermes converts the model’s Markdown to MarkdownV2 by default. Its Telegram docs describe a chain of fallbacks: a rich message Telegram refuses goes again as MarkdownV2, and “a message the Bot API still rejects as HTML is retried as MarkdownV2 before falling back to plain text”. By that account, a refused format costs a reply its formatting rather than the reply itself.
If it is your own bot
Pick one of three routes, by how much formatting you need.
Plain text. Leave parse_mode out and nothing is parsed, so nothing can fail. A good fallback is to retry a refused send this way: the reader gets the words, with the model’s asterisks showing.
Escape, then format. Text you insert into a template must be escaped for the mode you chose. For HTML that is &, < and > (Python’s html.escape(s, quote=False) does exactly that). For MarkdownV2, every reserved character, plus the backslash itself:
import re
def escape_markdown_v2(text):
return re.sub(r"([_*\[\]()~`>#+\-=|{}.!\\])", r"\\\1", text)CopiedThat makes text display literally. It does not make a model’s own Markdown valid MarkdownV2: for that the Markdown has to be parsed and re-emitted, escaping text and keeping the markup, which is what the agents above do.
Entities instead of a parse mode. The Bot API takes entities, a list of spans with a type, an offset and a length, “which can be specified instead of parse_mode”. The text is then sent as it is, with no characters reserved, so this error cannot occur; the price is computing offsets and lengths in UTF-16 code units yourself.
If the bot fails in other ways, the message thread not found error means it sent to a topic that is not there, a 409 Conflict means two programs read one token, and the Telegram setup guide walks the connection from the start.