{"record":{"id":"539b7f704bfa60c1","repo":"rust-lang/mdBook","slug":"unexpected-html-event-html","errorCode":null,"errorMessage":"`{}` unexpected Html event: {html}","messagePattern":"`(.+?)` unexpected Html event: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/mdbook-html/src/html/tree.rs","lineNumber":335,"sourceCode":"                }\n                Event::InlineMath(text) => {\n                    let mut span = Element::new(\"span\");\n                    span.insert_attr(\"class\", \"math math-inline\".into());\n                    self.push(Node::Element(span));\n                    self.append(Node::Text(text.into_tendril()));\n                    self.pop();\n                }\n                Event::DisplayMath(text) => {\n                    let mut span = Element::new(\"span\");\n                    span.insert_attr(\"class\", \"math math-display\".into());\n                    self.push(Node::Element(span));\n                    self.append(Node::Text(text.into_tendril()));\n                    self.pop();\n                }\n                Event::Html(html) => {\n                    // The loop in Tag::HtmlBlock should have consumed all\n                    // Html events.\n                    panic!(\n                        \"`{}` unexpected Html event: {html}\",\n                        self.options.path.display()\n                    );\n                }\n                Event::InlineHtml(html) => self.append_html(&html),\n                Event::FootnoteReference(name) => self.footnote_reference(name),\n                Event::SoftBreak => {\n                    self.append_text(\"\\n\".into());\n                }\n                Event::HardBreak => {\n                    self.append(Node::Element(Element::new(\"br\")));\n                }\n                Event::Rule => {\n                    self.append(Node::Element(Element::new(\"hr\")));\n                }\n                Event::TaskListMarker(checked) => {\n                    let mut input = Element::new(\"input\");\n                    input.insert_attr(\"disabled\", \"\".into());","sourceCodeStart":317,"sourceCodeEnd":353,"githubUrl":"https://github.com/rust-lang/mdBook/blob/dc21064fc21d955a0e1f67e65e336883c3e5260b/crates/mdbook-html/src/html/tree.rs#L317-L353","documentation":"mdbook-html's process_events assumes the dedicated HtmlBlock handling loop (in start_tag) consumes all pulldown-cmark Event::Html events, so receiving a raw Html event here is an invariant violation and panics. The panic includes the source file path to locate the offending chapter. This is an internal contract between the block-handling code and the main event loop.","triggerScenarios":"A pulldown-cmark Event::Html reaching the main event loop without being wrapped in an HtmlBlock — typically when a custom preprocessor emits raw HTML events, or a parser/version mismatch produces Html events outside html blocks.","commonSituations":"Using a preprocessor (e.g. one built on pulldown-cmark's programmatic API) that injects Event::Html directly into the stream, mixing incompatible pulldown-cmark versions between mdbook-html and a plugin, or parser changes that stop grouping raw HTML into HtmlBlock events.","solutions":["Identify the preprocessor producing raw Html events and change it to emit InlineHtml or wrap HTML in a proper html block.","Align pulldown-cmark versions between mdbook and any custom preprocessor so event grouping behavior matches.","Rebuild with preprocessors disabled (mdbook-preprocessor removal from book.toml) to isolate the culprit.","If no preprocessor is in use, report the parser-version combination as a bug to mdbook."],"exampleFix":"// before (preprocessor emitting raw html events)\nevents.push(Event::Html(String::from(\"<div class=\\\"note\\\">hi</div>\").into()));\n\n// after\nevents.push(Event::InlineHtml(String::from(\"<div class=\\\"note\\\">hi</div>\").into()));","handlingStrategy":"validation","validationCode":"// preprocessor: never emit bare Event::Html outside html blocks\nfor ev in &events {\n    if let Event::Html(_) = ev {\n        bail!(\"raw Html event outside HtmlBlock will break mdbook-html rendering\");\n    }\n}","typeGuard":null,"tryCatchPattern":"let out = std::panic::catch_unwind(|| process_events(events, &options));\nmatch out {\n    Ok(t) => t,\n    Err(_) => { eprintln!(\"unexpected Html event: audit preprocessors emitting Event::Html\"); std::process::exit(1); }\n}","preventionTips":["Prefer Event::InlineHtml in preprocessors for inline HTML.","Pin matching pulldown-cmark versions in your preprocessor and mdbook.","Test preprocessors against a minimal book before wide use."],"tags":["panic","internal-error","markdown-events","preprocessor"],"backgroundTag":"unexpected-html-event","analyzedSha":"dc21064fc21d955a0e1f67e65e336883c3e5260b","analyzedAt":"2026-09-01T10:15:12.134Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}