What causes "Failed to render doc" in BoundaryML/baml?

Retry rendering with a larger line width to rule out width-constraint failure.

Failed to render doc

Error message

Failed to render doc

What it means

After building an RcDoc render tree via formatter.schema_to_doc, format_schema calls doc.render(10, &mut w); if the pretty-printer fails (e.g. a doc structure that cannot fit width constraints, typically from infinite/nested doc constructs), it maps the failure to 'Failed to render doc'.

Solutions

Retry rendering with a larger line width to rule out width-constraint failure.
Reduce nesting in the BAML source (split large class/function definitions).
If it persists, file a bug: this indicates a formatter bug producing a non-renderable doc.

Defensive patterns

Strategy: try-catch

Try / catch

let formatted = match format_schema(source, &options) {
    Ok(f) => f,
    Err(e) if e.to_string().contains("Failed to render doc") => {
        // fall back to original source rather than failing the build
        source.to_string()
    }
    Err(e) => return Err(e),
};

Prevention

Keep BAML sources modestly nested; split very large class/function blocks.
Fall back to the unformatted source when rendering fails so tooling never hard-fails.
Test the formatter against your full corpus of .baml files in CI.

When it happens

Trigger: Calling format_schema on a schema whose parsed AST produces a malformed RcDoc that fails render at width 10 — e.g. pathological nesting or a doc built from an unsupported construct.

Common situations: Formatting a highly nested or unusual BAML schema that stresses the Wadler-style pretty printer, or a bug in a new formatter rule emitting an impossible doc.

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

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

Appendix: source

Thrown at engine/baml-lib/ast/src/formatter/mod.rs:46

    if ignore_directive_regex.is_match(source) {
        return Ok(source.to_string());
    }

    let mut schema = BAMLParser::parse(Rule::schema, source)?;
    let schema_pair = schema.next().ok_or(anyhow!("Expected a schema"))?;
    if schema_pair.as_rule() != Rule::schema {
        return Err(anyhow!("Expected a schema"));
    }

    let formatter = Formatter {
        indent_width: format_options.indent_width,
        fail_on_unhandled_rule: format_options.fail_on_unhandled_rule,
    };

    let doc = formatter.schema_to_doc(schema_pair.into_inner())?;
    let mut w = Vec::new();
    doc.render(10, &mut w)
        .map_err(|_| anyhow!("Failed to render doc"))?;
    String::from_utf8(w).map_err(|_| anyhow!("Failed to convert to string"))
}

macro_rules! next_pair {
    ($pairs:ident, $rule:expr) => {{
        loop {
            match $pairs.peek() {
                Some(pair) => {
                    if pair.as_rule() == Rule::NEWLINE {
                        $pairs.next();
                        continue;
                    }
                    if pair.as_rule() != $rule {
                        break Err(anyhow!(
                            "Expected a {:?}, got a {:?} ({}:{})",
                            $rule,
                            pair.as_rule(),
                            file!(),

View on GitHub (pinned to bd85ce9dee)