BoundaryML/baml · error · BamlValidationError

BamlValidationError

Error message

BamlValidationError: {message}

What it means

BamlValidationError is thrown by throw_baml_validation_error when the LLM output does not validate against the function's output schema. The thrown value is a JSON object containing the prompt, raw_output, and message, so callers can inspect what the model actually produced.

Solutions

  1. Inspect raw_output in the error payload to see the actual model response
  2. Tighten the prompt and output schema (add examples, simplify types)
  3. Add retry/retry-exponential policy to the client config so the model can self-correct
  4. Loosen the schema or use a more capable model if outputs are consistently invalid

Example fix

// before
class Answer { answer string }
// after
class Answer {
  answer string @description("The final answer, one sentence")
}
// plus in client config:
retry_policy ExtraRetries { max_retries 3 }
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: verify output schema expectations in the prompt include JSON-only instructions
const promptHasSchema = prompt.includes('Return JSON matching');

Type guard

const isBamlValidationError = (e: unknown): boolean => String(e).includes('BamlValidationError');

Try / catch

try {
  return await b.MyFunction(args);
} catch (e) {
  if (isBamlValidationError(e)) {
    const detail = JSON.parse(String(e).replace(/^[^{]*/, ''));
    console.error('Raw model output:', detail.raw_output);
    return null; // or retry with a corrective prompt
  }
  throw e;
}

Prevention

When it happens

Trigger: A generated BAML function's response fails schema/type validation — the parsed output doesn't match the declared return type — after all retries are exhausted.

Common situations: Model returns malformed JSON, omits required fields, emits wrong types, or drifts into prose instead of the requested structure; overly strict output schemas or weak prompts.

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

Appendix: source

Thrown at engine/language_client_typescript/src/errors.rs:151

    } else {
        napi::Error::new(napi::Status::GenericFailure, format!("BamlError: {err:?}"))
    }
}

fn throw_baml_validation_error(
    prompt: &str,
    raw_output: &str,
    message: &str,
    detailed_message: Option<&str>,
) -> napi::Error {
    let error_json = serde_json::json!({
        "type": "BamlValidationError",
        "prompt": prompt,
        "raw_output": raw_output,
        "message": format!("BamlValidationError: {}", message),
        "detailed_message": detailed_message,
    });
    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())
}

fn throw_baml_client_finish_reason_error(
    prompt: &str,
    raw_output: &str,
    message: &str,
    finish_reason: Option<&str>,
    detailed_message: Option<&str>,
) -> napi::Error {
    let error_json = serde_json::json!({
        "type": "BamlClientFinishReasonError",
        "prompt": prompt,
        "raw_output": raw_output,
        "message": format!("BamlError: BamlClientError: BamlClientFinishReasonError: {}", message),
        "finish_reason": finish_reason,
        "detailed_message": detailed_message,
    });
    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())

View on GitHub (pinned to bd85ce9dee)