BoundaryML/baml · error · StrongAstError

Expected token/node {expected_desc}, but found {found:?} at

Error message

Expected token/node {expected_desc}, but found {found:?} at {at:?}

What it means

StrongAstError::UnexpectedKindDesc is like UnexpectedKind but the expectation is described in human-readable text (a Cow<'static, str>) rather than a single SyntaxKind. It fires during FromCST conversion when the child found at a position does not satisfy a descriptive expectation (e.g. 'an expression' or 'a modifier'), carrying the found kind and its range.

Source

Thrown at baml_language/crates/baml_fmt/src/ast/mod.rs:51

///
/// Helps with conveniently printing error messages.
pub trait KnownKind {
    /// Should be constant, but we can't use `const` because it's a trait.
    fn kind() -> SyntaxKind;
}

/// Errors that can occur when parsing from a [`SyntaxNode`] with [`FromCST`].
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum StrongAstError {
    /// When an element is expected (of a specific [`SyntaxKind`]) but was found to be of a different kind.
    #[error("Expected token/node of kind {expected:?}, but found {found:?} at {at:?}")]
    UnexpectedKind {
        expected: SyntaxKind,
        found: SyntaxKind,
        at: TextRange,
    },
    /// When an element is expected but was found to be of a different kind.
    #[error("Expected token/node {expected_desc}, but found {found:?} at {at:?}")]
    UnexpectedKindDesc {
        expected_desc: Cow<'static, str>,
        found: SyntaxKind,
        at: TextRange,
    },
    /// When an element is expected (of a specific [`SyntaxKind`]) but there were no more children left.
    #[error("Expected token/node of kind {expected:?}, but was unable to find it in {parent:?}")]
    MissingExpectedElement {
        expected: SyntaxKind,
        parent: TextRange,
    },
    /// When an element is expected (not of a single specific [`SyntaxKind`]) but there were no more children left.
    #[error("Expected token/node {desc}, but was unable to find it in {parent:?}")]
    MissingExpectedElementDesc {
        desc: Cow<'static, str>,
        parent: TextRange,
    },
    /// When the node isn't expected to have any more children (e.g. a statement found a `;`) but there are still children left.

View on GitHub (pinned to bd85ce9dee)

Solutions

Use `at` to locate and correct the offending BAML syntax in the source file
Check for parser errors before conversion; a lossy/error tree often triggers this
Align parser and baml_fmt crate versions so the CST shape matches the AST builder's expectations
If constructing trees manually, ensure children satisfy the documented expectation

Defensive patterns

Strategy: validation

Validate before calling

// check the child satisfies the descriptive expectation before conversion
if !expected_desc_matches(child.kind()) {
    return Err(format!("expected {}, found {:?}", expected_desc, child.kind()));
}

Type guard

fn matches_desc(k: SyntaxKind, desc: &str) -> bool { /* kind set for desc */ expected_desc_matches(k) }

Try / catch

match StrongAst::from_cst(node) {
    Ok(ast) => use(ast),
    Err(StrongAstError::UnexpectedKindDesc { expected_desc, found, at }) => {
        report(at, format!("expected {expected_desc}, found {found:?}"));
    }
    Err(e) => report_all(e),
}

Prevention

Re-parse and clear all parser errors before formatting
Align grammar and AST-builder versions
Use `at` and `expected_desc` messages to fix source syntax precisely
Avoid hand-mutating syntax trees

When it happens

Trigger: FromCST strong-AST conversion encounters a child whose kind does not match a multi-kind or descriptive expectation at the conversion site — anywhere the AST builder calls expect-style helpers with a description string instead of one exact SyntaxKind.

Common situations: Malformed BAML source that parses into a tree the AST layer cannot interpret; grammar/parser version drift producing unexpected node shapes; programmatic construction of syntax trees with wrong children.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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