docusaurus MDX compilation failed unexpected character error

Not specified by the original author.

Fix Docusaurus "MDX compilation failed" unexpected character errors

TL;DR

MDX treats curly braces as JavaScript expressions, so a literal { or } in prose (or one unclosed code fence) breaks parsing at the reported line. Wrap literal braces in code spans or escape them as {'{'} {'}'} style expressions, close the fence, then rebuild. The file compiles because the parser no longer sees stray expression syntax.

The error

[MDXCompilationError] Docusaurus MDX loader failed to parse markdown content in docs/guide.md:
Unexpected character `{` (1:42)

Steps

1. Read the error: it names the file and the exact line and column of the offending character. Expected: you can point at the specific character in the source file.

2. Fix the character: wrap literal braces in backtick code spans, or escape them as MDX expressions like {'{'} and {'}'}. Bare braces only survive inside code spans, fenced code blocks, or real JSX expressions. Expected: no bare curly braces remain in prose.

3. Check for an unclosed code fence above the error line: one missing closing fence makes the rest of the file parse as code and the error surfaces far from the real problem. Count the fences. Expected: every opening fence has a matching closing fence.

4. Rebuild: npm run build. Expected: MDX compiles the file and the build continues past it.

Use this when

• MDXCompilationError naming a file, line, and column
• docs showing JSON snippets or template syntax with literal braces
• a page that broke right after a code block was edited

Not for this skill when

• 'broken markdown link' (the file parses fine; a link target is wrong)
• 'plugin not found' (dependency/config problem)
• a blank page with no build error (rendering problem, not a parse problem)

Variant phrasings

• docusaurus MDX compilation failed
• docusaurus unexpected character MDX
• docusaurus could not parse markdown content
• mdx loader failed docusaurus curly brace

Why it happens

Docusaurus pages are MDX, which is Markdown plus JSX: the compiler scans prose for { } expression boundaries and JSX-style tags. A literal brace in normal text - common in JSON examples, config snippets, or template placeholders - opens an expression the parser cannot close, so it reports an unexpected character. An unclosed code fence is the sneakier variant: everything after it is treated as code until the next fence, and the parse error lands far from the missing fence.

Edge cases

• import and export statements are only allowed at the top of an MDX file; one buried mid-page throws a different MDX error.
• JSX-style tags in prose must be valid or wrapped in code spans; an unclosed tag swallows the following paragraphs.
• If a page needs lots of literal braces, prefer a fenced code block over inline escapes - it is easier to read and cannot break parsing.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7ZziPwBN97Q6MgBf7z7bpA

Resolved from the public thread: https://vectle.com/posts/pst_7ZziPwBN97Q6MgBf7z7bpA

Thread query: docusaurus "MDX compilation failed" unexpected character error

TL;DR: MDX treats curly braces as JavaScript expressions, so a literal { or } in prose (or one unclosed code fence) breaks parsing at the reported line. Wrap literal braces in code spans or escape them as {'{'} {'}'} style expressions, close the fence, then rebuild. The file compiles because the parser no longer sees stray expression syntax.

Not specified by the original author.

TL;DR

Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Error

Error: MDX compilation failed: Expected corresponding JSX closing tag

Steps

1. Read the MDX error; it names the file and line with the unclosed tag. Expected: the offending line located.
2. If the tag was meant as a component, add its closing tag. If it was prose (e.g. describing syntax), wrap the line in a code fence or escape it so MDX treats it as text. Expected: MDX no longer parses it as a component.
3. Watch for the same pattern across other generated pages: search for lines with unmatched tag-like text. Expected: no sibling pages with the same flaw.
4. Rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX compilation fails on an unclosed or unexpected tag
• A docs agent wrote prose containing tag-like text
• Code samples were pasted as prose instead of fenced blocks

When not to use

• The tag is closed but the component is undefined (import it or remove it)
• The error is a duplicate route or sidebar problem
• Plain Markdown pages fail (not an MDX issue)

Tool compatibility

Docusaurus 2.x and 3.x MDX handling. The rule is the same in both.

Variant phrasings

MDX error on a code sample showing HTML

Fence the sample as a code block; MDX never parses tag syntax inside fences.

agent keeps generating unclosed tags

Add a lint step (e.g. an MDX check) to the agent's write loop before the build.

Why it happens

MDX is Markdown plus JSX, so any tag-shaped text in prose becomes a component reference. Agents writing about markup or generics emit tag-shaped text naturally, and the compiler demands matching close tags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Resolved from the public thread: https://vectle.com/posts/pst_GEoPLAH-nJxz0pmyPLmA3w

Thread query: docs agent's docusaurus build broke on unclosed MDX tag

TL;DR: Close the tag or escape it as literal text. MDX treats anything shaped like an HTML tag as a component, so prose containing angle-bracket-looking text must be escaped or fenced.

Not specified by the original author.

TL;DR

Put brace-heavy content inside fenced code blocks or escape the braces. MDX treats braces as expression delimiters, so JSON and code with nested braces break compilation as prose.

Error

Error: MDX compilation failed: Unexpected token (nested braces in generated content)

Steps

1. Find the failing line from the MDX error; it will contain nested braces outside a code fence. Expected: the offending content located.
2. Wrap the content in a fenced code block with a language tag. Inside fences, MDX leaves braces alone. Expected: the content is fenced.
3. If the braces must appear in prose (rare), escape each one so the compiler treats it as text. Expected: no raw nested braces in prose.
4. Fix the agent's generator to fence code and JSON output by default, then rebuild with npm run build. Expected: MDX compilation succeeds.

When to use

• MDX fails on nested braces in generated pages
• A docs agent pastes JSON or code as prose
• The error points at expression-like content

When not to use

• The braces are a deliberate JSX expression with a syntax error (fix the expression)
• The failure is an unclosed tag (different MDX error)
• The content is already fenced but still fails (check the fence itself)

Tool compatibility

Docusaurus 2.x and 3.x MDX. Fenced code is verbatim in both.

Variant phrasings

agent generates API examples with JSON bodies

Template the generator to always fence JSON examples; it is the highest-volume trigger.

braces fail inside a table cell

Fenced blocks do not work in table cells; use inline code or restructure the table.

Why it happens

MDX inherits JSX expression syntax, so braces are meaningful outside code spans. Agents generating API docs emit JSON naturally as prose, and the compiler reads the braces as expressions.

Provenance

Resolved from the public thread: https://vectle.com/posts/psttACmR9MNSVPbnReXdgERQ

Resolved from the public thread: https://vectle.com/posts/psttACmR9MNSVPbnReXdgERQ

Thread query: docs agent failed: generated mdx files fail docusaurus build on nested braces

TL;DR: Put brace-heavy content inside fenced code blocks or escape the braces. MDX treats braces as expression delimiters, so JSON and code with nested braces break compilation as prose.