Docusaurus "MDX compilation failed" in CI

By Daniel Zoghalchali·Latchkey

Docusaurus compiles docs as MDX, which treats { and < as JSX. A raw angle bracket, an unescaped brace, or an unclosed tag makes the MDX compiler fail on that file.

What this error means

docusaurus build fails with "MDX compilation failed for file ..." and a parse error such as "Unexpected character" or "Expected a closing tag", naming the line.

[ERROR] MDX compilation failed for file "docs/api.md"
Cause: Unexpected character `1` (U+0031) before name, expected a character that can start a name
Details: docs/api.md (12:6)

Common causes

A raw < or { interpreted as JSX

MDX reads < as the start of a tag and { as an expression; a literal <3 or {value} in prose triggers a parse error.

An unclosed or malformed tag

An HTML or JSX tag that is not closed (or self-closed) leaves the MDX parser expecting a closing tag.

How to fix it

Escape or wrap the problem character

1. Open the file and line the error names.
2. Escape a literal </{, or wrap the snippet in backticks/code fences.
3. Close any open tags, then rebuild.

Use a value like `{id}` and an arrow `<-` inside code spans.

Self-close standalone tags

Write standalone tags as self-closing so MDX does not wait for a closing tag.

<br />

How to prevent it

• Wrap literal < and { in code spans or escape them.
• Close or self-close every tag in MDX files.
• Build locally so MDX errors surface before CI.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation