BoundaryML/baml · error · StreamingError

Class instance did not contain fields marked as needed: {fie

Error message

Class instance did not contain fields marked as needed: {fields:?}

What it means

StreamingError::MissingNeededFields fires when a streamed class instance is considered complete but lacks fields whose streaming_behavior marks them as needed. BAML lets fields be declared 'needed' for streaming correctness; a Done value missing them violates that contract.

Source

Thrown at engine/baml-lib/jsonish/src/deserializer/semantic_streaming.rs:26

    BamlMap, BamlValueWithMeta, Completion, CompletionState, ResponseCheck, TypeIR, TypeValue,
};
use indexmap::{IndexMap, IndexSet};
use internal_baml_core::ir::{
    ir_helpers::infer_type_with_meta,
    repr::{IntermediateRepr, Walker},
    Field, IRHelper, IRHelperExtended, IRSemanticStreamingHelper,
};
use thiserror;

use crate::{deserializer::coercer::ParsingError, BamlValueWithFlags, Flag};

#[derive(Debug, thiserror::Error)]
pub enum StreamingError {
    #[error("Expected to encounter a class")]
    ExpectedClass,
    #[error("Value was marked Done, but was incomplete in the stream")]
    IncompleteDoneValue,
    #[error("Class instance did not contain fields marked as needed: {fields:?}")]
    MissingNeededFields { fields: Vec<String> },
    #[error("Failed to distribute_type_with_meta: {0}")]
    DistributeTypeWithMetaFailure(#[from] anyhow::Error),
}

/// For a given baml value, traverse its nodes, comparing the completion state
/// of each node against the streaming behavior of the node's type.
pub fn validate_streaming_state(
    ir: &impl IRHelperExtended,
    baml_value: &BamlValueWithFlags,
    mode: baml_types::StreamingMode,
) -> Result<BamlValueWithMeta<Completion>, StreamingError> {
    let baml_value_with_meta_flags: BamlValueWithMeta<Vec<Flag>> = baml_value.clone().into();
    let typed_baml_value: BamlValueWithMeta<(Vec<Flag>, TypeIR)> =
        ir.distribute_type_with_meta(baml_value_with_meta_flags, baml_value.field_type().clone())?;
    let baml_value_with_streaming_state_and_behavior =
        typed_baml_value.map_meta(|(flags, r#type)| (completion_state(flags), r#type));

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Review which fields are marked needed in the class's streaming behavior and confirm the prompt asks for all of them.
2. Increase max_tokens or adjust stop conditions so the model can emit every field.
3. Make the field optional in the schema if it is not truly required.
4. Retry the generation; log the missing field names from the error for prompt iteration.

Example fix

// before: field required but often missing
class Resume { name string @stream.needed  skills string[] @stream.needed }
// after: relax if optional
class Resume { name string  skills string[]? }

// after streaming completes, verify needed fields present
for f in needed_fields_of(class_type) {
    if !value_has_field(&value, &f.name) {
        return Err(anyhow::anyhow!("needed field missing: {}", f.name));
    }
}

fn has_needed_fields(v: &BamlValueWithFlags, needed: &[String]) -> bool {
    needed.iter().all(|f| v.field(f).map(|x| x.is_done()).unwrap_or(false))
}

match validate_streaming_state(&value) {
    Err(StreamingError::MissingNeededFields { fields }) => {
        log::warn!("model omitted needed fields: {fields:?}");
        retry_with_reinforced_prompt(&fields).await?
    }
    other => other?,
}

When it happens

Trigger: validate_streaming_state finishes traversal on a class node marked Done while one or more fields with streaming_needed=true never appeared or never completed in the stream.

Common situations: Model omitted a required field in its JSON output; field declared with @stream.done or needed semantics but the model never emits it; truncation dropping trailing fields.

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

• log event omitted call
• Enum {name} not found
• Class {name} not found
• Recursive alias {name} not found
• Expected to encounter a class

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