nbconvert to rst failed with unknown node type error in mistune

Not specified by the original author.

TL;DR

The RST writer walks the notebook through mistune, and an output node type it does not know (a newer widget output, a custom mimebundle) raises 'unknown node type'. Identify the cell whose output triggers it by converting with outputs stripped versus kept, then either clear that cell's outputs or pin a mistune version whose RST renderer knows the node. RST is a narrow format; rich outputs often do not survive it.

nbconvert to rst failed with unknown node type error in mistune

Use this when

• RST export fails with mistune complaining about an unknown node type.
• HTML export of the same notebook works.
• The notebook has widget or custom-mimetype outputs.

Not for this skill when

• The export fails on templates. That is a template problem.
• RST generates but renders oddly. That is renderer fidelity.

Steps

1. Bisect: export with --clear-output first. Verify: it succeeds, proving an output node is the trigger.
2. Re-add outputs in halves to find the offending cell. Verify: you can name the cell and its output type.
3. Clear or simplify that cell's outputs (replace widget output with a static figure). Verify: the export passes.
4. Alternatively, pin mistune to a version whose RST support covers your nodes. Verify: the export passes with outputs kept.
5. Re-run the full RST export. Verify: the .rst is written without node errors.

Variant phrasings

nbconvert rst unknown node type

Short form. An output node mistune cannot render.

mistune error nbconvert rst

Library phrasing. Bisect the outputs.

rst export failed jupyter

General phrasing. RST is narrow; simplify outputs.

Compatibility: nbconvert 6/7 with mistune 2/3. Node coverage differs by mistune version.

Why it happens

RST is a much narrower format than HTML: it has no native concept of interactive widgets or arbitrary mimebundles. nbconvert's RST path leans on mistune's renderer, which only knows the node types its authors implemented. A notebook that is fine as HTML can contain output nodes that are simply unrepresentable in RST, and mistune reports that honestly as an unknown node.

Edge cases / pitfalls

• Pinning mistune for one export can break other tools that need a newer mistune. Isolate the export env if needed.
• Stripping outputs loses information in the .rst. Prefer simplifying the output over deleting it.
• Custom mime types from extensions are the usual unknown nodes. Check what extensions the notebook uses.
• If RST is a hard requirement, design notebooks for it: static figures and text tables only.

Provenance

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

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

Thread query: nbconvert to rst failed with unknown node type error in mistune

TL;DR: The RST writer walks the notebook through mistune, and an output node type it does not know (a newer widget output, a custom mimebundle) raises 'unknown node type'. Identify the cell whose output triggers it by converting with outputs stripped versus kept, then either clear that cell's outputs or pin a mistune version whose RST renderer knows the node. RST is a narrow format; rich outputs often do not survive it.