sphinx ERROR: Failed to load extension 'myst_parser' build failed

Not specified by the original author.

TL;DR

Install the myst-parser package into the environment running the build and spell the extension name exactly myst_parser in conf.py. The package name on PyPI uses a hyphen while the extension module uses an underscore.

Error

ERROR: Failed to load extension 'myst_parser'

Steps

1. Check whether the package is installed in the build environment: pip show myst-parser. Expected: either version info or "not installed", which tells you which fix applies.
2. Install it with pip install myst-parser, pinning a version compatible with your Sphinx release (myst-parser 2.x pairs with Sphinx 7+, 3.x with Sphinx 8). Expected: pip reports a successful install.
3. Open conf.py and confirm the extensions list contains the string myst_parser exactly, not myst-parser or myst. Expected: the underscore spelling is present.
4. Rebuild with sphinx-build -b html docs docs/_build. Expected: the extension loads and Markdown sources parse.

When to use

• The build fails naming myst_parser as the unloadable extension
• You added Markdown sources to a previously RST-only project
• CI or Read the Docs fails while the local build works

When not to use

• The extension loads but Markdown renders wrong (a myst configuration issue, not a load failure)
• You meant to use recommonmark, which is a different package and extension name
• The failure names a different extension

Tool compatibility

Sphinx 7.x/8.x with myst-parser 2.x/3.x. If you are stuck on Sphinx 5 or 6, use myst-parser 1.x.

Variant phrasings

Sphinx reports "No module named 'myst_parser'"

Same root cause: the package is missing from the build environment. Install it.

extension loads locally but not on Read the Docs

Add myst-parser to the docs requirements file that Read the Docs installs; the local environment is irrelevant to the hosted build.

Why it happens

The PyPI distribution name (myst-parser) differs from the importable module name (myst_parser), so installs and config edits get out of sync. Clean CI environments expose the missing dependency that a developer's laptop hides.

Provenance

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

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

Thread query: sphinx "ERROR: Failed to load extension 'myst_parser'" build failed

TL;DR: Install the myst-parser package into the environment running the build and spell the extension name exactly myst_parser in conf.py. The package name on PyPI uses a hyphen while the extension module uses an underscore.

Not specified by the original author.

TL;DR

Lint every generated .rst file with docutils before building: parse it with publish_doctree set to halt on warnings, fix what it flags, then build. LLM writers produce plausible-looking RST with broken directive indentation and missing blank lines. A 2-second lint catches what a 2-minute build failure only hints at.

docs agent's llm writer produced invalid rst, sphinx build failed

Steps

1. Find the offending file: read the sphinx-build error; it names the .rst file and line number. Open that spot. Expected: you can see the malformed markup (bad indent, directive run into text, unknown directive).
2. Lint the file directly: python -c "from docutils.core import publish_doctree; publish_doctree(open('docs/api/broken.rst').read(), settings_overrides={'report_level': 2, 'halt_level': 2})". Expected: it raises on the same problem Sphinx hit, instantly, without a full build.
3. Fix the usual LLM RST mistakes: directives need a blank line before them and their content indented consistently (three spaces is the safe convention); inline markup needs matching delimiters; unknown directives usually mean the writer invented a directive name, replace it with a real one.
4. Re-lint until clean, then run the full sphinx-build. Expected: exit 0 and the page renders.
5. Add the lint as a gate in the agent loop: every generated .rst file is parsed before the build step, and a parse failure fails the run with the file and line. Expected: invalid RST never reaches sphinx-build again.

Use this when

• sphinx-build fails on agent-generated .rst files
• the error names a file the LLM writer produced
• you want a fast pre-build check for generated RST

Not for this skill when

• hand-written RST fails (same lint helps, but the fix is editing, not agent gating)
• the build fails on valid RST (extension or config problem)
• you use Markdown sources instead (lint the Markdown, different tool)

Variant phrasings

• llm generated rst does not build
• sphinx errors on ai-written rst
• invalid restructuredtext from docs agent

Why it happens

LLMs learn RST from rendered examples, not from the spec, so they reproduce the look of directives while getting the whitespace rules wrong: missing blank lines, inconsistent indentation, invented directive names. Sphinx is strict about these, so the build fails on markup that reads fine to a human.

Edge cases

• Plain docutils does not know Sphinx-specific directives: for those, treat Sphinx's own error as the final word.
• A file can parse yet render badly (wrong nesting): spot-check the rendered page for generated files.
• Mixed line endings can confuse the parser: normalize generated files to LF.
• Very long lines from the writer are legal but unreadable: wrap them for future debuggability.

Provenance

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

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

Thread query: docs agent's llm writer produced invalid rst, sphinx build failed

TL;DR: Lint every generated .rst file with docutils before building: parse it with publish_doctree set to halt on warnings, fix what it flags, then build. LLM writers produce plausible-looking RST with broken directive indentation and missing blank lines. A 2-second lint catches what a 2-minute build failure only hints at.

Not specified by the original author.

TL;DR

Teach the agent to stop validating directives it does not know: either parse with the project's Sphinx extensions loaded, or treat unknown directives as opaque blocks (directive line plus indented body, no argument checking). This fixes the failure because directive syntax (allowed arguments, options, body shape) is defined by each directive's class, not by generic RST rules, so a generic parser can never validate custom ones correctly.

The error

agent's sphinx directive parser failed on custom extensions

Steps to fix

1. Reproduce the failure: run the agent's parser over the failing .rst file and record the exact directive name it chokes on (the line starting with .. followed by the name and ::).

   • Expected: one or two directive names, not a broad parse failure across the whole tree.

2. Open the project's conf.py and find which extension registers that directive (search for add_directive calls or the extension module name in the extensions list).

   • Expected: the directive maps to a project extension, confirming the parser just doesn't know it.

3. Apply the fix. Option A (best): parse through Sphinx's own machinery with the project's conf.py loaded so every custom directive is registered before parsing. Option B (simpler): add the custom directive names to the agent parser's known-directive table as opaque blocks - consume the directive line and its indented body verbatim without validating arguments or options.

   • Expected: the parser accepts the custom directive lines without error.

4. Re-run the parser over the entire docs tree and diff the extracted text against the previous run.

   • Expected: zero parse errors, and the custom directive content is preserved in the output.

Use this when

• A docs agent parses .rst files with its own parser and fails only on files using custom directives.
• The failing directive names are registered by extensions in the project's conf.py.
• The agent needs directive text extracted, not validated (summaries, search indexing, doc sync).

Not for this skill when

• Sphinx itself fails to build (that's a build config problem, not an agent parser problem).
• The failure is on standard directives like note or code-block (check the parser's built-in directive table instead).
• The agent generates directives rather than parsing them.

Variant phrasings

• docs agent can't parse custom sphinx directives
• sphinx directive parser error on project-specific extensions
• agent rst parser fails on unknown directive
• custom admonition directive breaks docs agent parsing

Why it happens

RST directives are an extension point: .. name:: can take any arguments, options, and body shape depending on the registered directive class. A standalone parser only knows the built-in directive set, so when it meets a custom one it either rejects the unknown name or misparses its arguments. The parser was written against the generic RST grammar, but custom directives don't follow a generic grammar - they follow whatever the extension author defined.

Edge cases

• Directives registered via plain docutils (not Sphinx) in a standalone module: conf.py won't list them, so scan for directives modules in the repo too.
• Nested directives inside a custom directive's body: the opaque-block approach must still recurse into the body for nested standard directives.
• Custom roles (single-backtick roles) fail the same way: apply the same known-or-opaque treatment to roles.
• Option parsing differences: never try to validate options on an opaque directive, just carry them through verbatim.

Provenance

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

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

Thread query: agent's sphinx directive parser failed on custom extensions

TL;DR: Teach the agent to stop validating directives it does not know: either parse with the project's Sphinx extensions loaded, or treat unknown directives as opaque blocks (directive line plus indented body, no argument checking). This fixes the failure because directive syntax (allowed arguments, options, body shape) is defined by each directive's class, not by generic RST rules, so a generic parser can never validate custom ones correctly.