BoundaryML/baml · error · StrongAstError

An element at {at:?} was a node when it should have been a t

Error message

An element at {at:?} was a node when it should have been a token.

What it means

StrongAstError::ShouldBeNode is raised when the FromCST conversion expects the current child element to be a composite node but it is actually a bare token. The strong-AST builder distinguishes tokens from nodes; receiving the wrong element type at `at` aborts conversion.

Source

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

        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.
    #[error("Unexpected additional element at {at:?} in {parent:?}")]
    UnexpectedAdditionalElement { parent: TextRange, at: TextRange },
    /// When an element is expected to be a node but it's actually a token.
    #[error("An element at {at:?} was a node when it should have been a token.")]
    ShouldBeNode { at: TextRange },
    /// When an element is expected to be a token but it's actually a node.
    #[error("An element at {at:?} was a token when it should have been a node.")]
    ShouldBeToken { at: TextRange },
}
impl StrongAstError {
    /// Checks that the given node is of the specified [`SyntaxKind`].
    ///
    /// # Errors
    /// Returns [`StrongAstError::UnexpectedKind`] if the element not the expected kind.
    pub fn assert_kind_node(node: &SyntaxNode, expected: SyntaxKind) -> Result<(), Self> {
        if node.kind() == expected {
            Ok(())
        } else {
            Err(Self::UnexpectedKind {
                expected,
                found: node.kind(),
                at: node.text_range(),

View on GitHub (pinned to bd85ce9dee)

Solutions

Check the source at `at` and fix the BAML syntax so the expected structure is present
Fix parser errors first — error recovery can substitute tokens for nodes
Keep parser and formatter crate versions aligned
When building trees manually, wrap children in the proper node kind

Defensive patterns

Strategy: type-guard

Validate before calling

// verify the element at the position is a node, not a token
let el = parent.children_with_tokens().next()?;
if matches!(el, SyntaxElement::Token(_)) {
    return Err("expected node, found token");
}

Type guard

fn is_node(e: &SyntaxElement) -> bool { matches!(e, SyntaxElement::Node(_)) }

Try / catch

match StrongAst::from_cst(node) {
    Ok(ast) => use(ast),
    Err(StrongAstError::ShouldBeNode { at }) => {
        report(at, "expected a node but found a token");
    }
    Err(e) => report_all(e),
}

Prevention

Fix parser recovery artifacts by clearing parse errors first
Keep parser and baml_fmt versions aligned
Wrap children in proper node kinds when constructing trees manually
Check the `at` range source for flattened/malformed syntax

When it happens

Trigger: A conversion helper that descends into a child node (e.g. to build a nested statement or expression) encounters a leaf token at that position instead — the CST places a token where the grammar requires a subtree.

Common situations: Flattened or malformed trees from parser recovery; version drift between parser and baml_fmt; hand-constructed trees attaching tokens where nodes are required.

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/89f7e87b86f14753. Report an issue: GitHub.