BoundaryML/baml · error

Encountered impossible doc comment during parsing: {:?}, {:?

Error message

Encountered impossible doc comment during parsing: {:?}, {:?}

What it means

parse_doc_comment unwraps the first child of a doc-comment token and accepts only Rule::doc_content or nested Rule::doc_comment; anything else triggers unreachable!('Encountered impossible doc comment...'). This is a parser invariant: the pest grammar should only produce those two shapes inside doc comments.

Source

Thrown at engine/baml-lib/ast/src/parser/parse_comments.rs:60

            _ => parsing_catch_all(current, "trailing comment", diagnostics),
        }
    }

    if lines.is_empty() {
        None
    } else {
        Some(Comment {
            text: lines.join("\n"),
        })
    }
}

pub(crate) fn parse_doc_comment(token: Pair<'_>) -> &str {
    let child = token.into_inner().next().unwrap();
    match child.as_rule() {
        Rule::doc_content => child.as_str().trim_start(),
        Rule::doc_comment => parse_doc_comment(child),
        x => unreachable!(
            "Encountered impossible doc comment during parsing: {:?}, {:?}",
            x,
            child.tokens()
        ),
    }
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Rebuild with grammar and parser code from the same crate version.
2. Check the debug payload ({:?} of the rule and tokens) to identify the unexpected rule and update parse_doc_comment's match.
3. Report the input snippet upstream if it occurs on a stock release.

let child = token.clone().into_inner().next();
let ok = matches!(
    child.as_ref().map(|c| c.as_rule()),
    Some(Rule::doc_content) | Some(Rule::doc_comment)
);
if !ok {
    eprintln!("unexpected doc comment shape; skipping");
}

fn is_valid_doc_comment(token: &Pair<Rule>) -> bool {
    matches!(
        token.clone().into_inner().next().map(|c| c.as_rule()),
        Some(Rule::doc_content) | Some(Rule::doc_comment)
    )
}

let r = std::panic::catch_unwind(|| parse_doc_comment(token.clone()));
if r.is_err() {
    return Err(anyhow!("malformed doc comment"));
}

When it happens

Trigger: Calling parse_doc_comment (directly or via parse_comment_block/parse_trailing_comment) with a doc_comment pair whose child rule is neither doc_content nor doc_comment — grammar/code desync or malformed token stream.

Common situations: Custom or mismatched builds of the ast crate where the comment grammar rules were renamed/added; fuzzed or hand-crafted parse trees.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Name should always be defined for attribute.
• c_for_init_stmt cannot accept empty input
• c_for_after_stmt cannot accept empty input
• block aware tail expression is not empty
• Unexpected prefix operator: {:?}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/96c21cf7d5a0149c. Report an issue: GitHub.