Telegram Bot 'Bad Request: Can't Parse Entities'? 6 Causes and Fixes (2026)
What does "Bad Request: can't parse entities" mean in a Telegram bot?
It means you sent a message with parse_mode set to MarkdownV2, Markdown or HTML, and the text breaks that mode's rules, so the Bot API rejected the whole message with a 400 error. Nothing was delivered. The usual cause is one unescaped character, such as a dot or a hyphen in MarkdownV2, or a bare & or < in HTML. This guide lists the six causes we see most, with the exact rule from Telegram's Bot API documentation for each, checked on 2026-11-17, and a safe pattern for text you don't control.
The 6 causes at a glance
Read the second half of the error first: it names the problem, and usually a byte offset in your text where parsing failed.
| # | Cause | Typical error detail | Fix |
|---|---|---|---|
| 1 | Reserved character not escaped in MarkdownV2 | Character '.' is reserved and must be escaped | Escape all 18 reserved characters |
| 2 | Entity opened but never closed | Can't find end of the entity starting at byte offset N | Close or escape the stray * or _ |
| 3 | Text written for one mode, sent with another | Varies | Match parse_mode to the syntax |
| 4 | Unsupported tag or bare &, <, > in HTML | Unsupported start tag | Use only listed tags; escape the rest |
| 5 | Wrong escaping inside code, pre or link URLs | Varies | Use the context rules |
| 6 | Text cut through the middle of an entity | Can't find end of the entity | Cut on boundaries; respect the length limits |
1. Is a reserved MarkdownV2 character unescaped?
Most likely yes. Telegram's formatting rules say that outside entities, these 18 characters must be escaped with a preceding backslash: _ * [ ] ( ) ~ ` > # + - = | { } . !. That includes the full stop at the end of a sentence, the hyphen in "e-mail", the plus in a phone number and the brackets in "(beta)".
The same docs add that any character with a code from 1 to 126 can be escaped anywhere, so over-escaping plain ASCII is safe, and a literal backslash must itself be escaped. In Python, python-telegram-bot ships telegram.helpers.escape_markdown(text, version=2); apply it to each variable you insert, not to the whole template, or you'll escape your own formatting too.
2. Did a * or _ open an entity that never closes?
If the detail says it can't find the end of an entity, a formatting marker has no partner. Usernames are the classic case: inserting john_doe into a MarkdownV2 message opens italics at the underscore and never closes it. AI-generated text causes the same problem, because chat models write standard Markdown, which is close to MarkdownV2 but not the same.
The byte offset points into the UTF-8 bytes of your text, so emoji or accented letters earlier in the message move the number. Log the exact text you sent alongside the error, then count bytes, not characters, to find the spot. If the offset lands on a name or a value from your database, escape that value; if it lands inside your own template, the template itself has an unbalanced marker.
3. Does the parse_mode match the syntax you wrote?
It has to. Telegram supports three modes: MarkdownV2, the older Markdown kept for compatibility, and HTML. Their syntax differs: __underline__ and ||spoiler|| exist only in MarkdownV2, and legacy Markdown doesn't require escaping dots. Many libraries and no-code tools set a default mode, so check what your request actually sends before debugging the text.
If you don't need formatting at all, leave parse_mode out. Plain text has nothing to parse, so this error can't happen.
4. Is your HTML using a tag Telegram doesn't support?
Telegram's HTML mode accepts only a short list of tags: b, strong, i, em, u, ins, s, strike, del, a, code, pre, blockquote, the spoiler tags and a few Telegram-specific ones. Its docs say only those tags are supported, and that every <, > and & that isn't part of a tag or entity must be replaced with <, > and &. Common failures are a <br> or <p> copied from a web page, and an "R&D" or "a < b" in user text.
Only four named entities are accepted: <, >, & and ". Numeric entities all work. Use a newline character instead of <br>.
5. Are code blocks and link URLs escaped by their own rules?
They have different rules from normal text. Inside pre and code entities, only the backtick and the backslash must be escaped, and inside the (...) part of an inline link, only ) and the backslash. One global escape function applied to the whole message therefore corrupts code samples and URLs. Build the message in parts: escape plain text with the text rules, code with the code rules and URLs with the URL rules.
6. Did truncation cut an entity in half?
If you shorten long text before sending, you can cut between an opening and a closing marker. The Bot API limits sendMessage text to 1 to 4,096 characters after entities parsing, and media captions to 0 to 1,024. Trim on a paragraph boundary, then escape, then check the length; trimming already-escaped text can split an escape sequence too.
If you're also posting the same text to X, the rules change again, because X counts characters differently; our explainer on converting Telegram text to X's weighted character count covers that step.
What's the safest pattern for user or AI text?
Use HTML mode and escape every inserted value, or send plain text with an explicit entities array. HTML needs three characters escaped instead of eighteen, which is why it is the easier mode for dynamic content. With an entities array you pass offsets and types yourself, so Telegram parses nothing. Add a test that sends awkward strings, such as names with underscores, prices with dots, "R&D" and an emoji, through your formatter.
A message that fails here never reaches the queue, so this check pairs with the others in a bot's error handling: 429 rate limits and retry_after, the 409 getUpdates conflict and webhooks that stop delivering updates. Unlike a 429, a parse error is deterministic: retrying the same text fails every time. Once formatting parses, the next edit error you may meet is a no-op edit; see why editMessageText returns message is not modified.
If you only want to schedule posts to X from Telegram rather than build a bot yourself, the Auto X Telegram bot does that; it's our own product, and the Auto X homepage lists its plans. Entities parsing also counts toward Telegram's 4096-character sendMessage limit; see how to split a sendMessage that is over 4096 characters.
FAQ
Does Telegram send the message without formatting when parsing fails?
No. The Bot API returns a 400 error and sends nothing. Your code has to catch the error and either fix the text or resend it without a parse mode.
Which characters must be escaped in Telegram MarkdownV2?
Outside entities: underscore, asterisk, both square brackets, both round brackets, tilde, backtick, greater-than, hash, plus, minus, equals, pipe, both curly braces, dot and exclamation mark. Inside code and pre, only the backtick and backslash.
Is HTML or MarkdownV2 better for a Telegram bot?
For text you don't control, HTML is easier, because only <, > and & need escaping. MarkdownV2 is fine for fixed templates you write and test yourself.
Why does the error only happen sometimes?
Because it depends on the text. The same template works until a name, price or AI reply contains a reserved character, so the failure looks random while being fully repeatable for that input.
Sources
- Telegram Bot API: Formatting options (MarkdownV2, HTML, Markdown) (checked 2026-11-17)
- Telegram Bot API: sendMessage text limit and parse_mode (checked 2026-11-17)
- python-telegram-bot: telegram.helpers.escape_markdown (checked 2026-11-17)