BoundaryML/baml · error · anyhow::Error

BAML internal error (openai-responses): content part must be

Error message

BAML internal error (openai-responses): content part must be an object

What it means

When applying provider metadata to a Responses API content part, BAML expects the serialized part to be a JSON object. If the recursive responses_content_part call produced a non-object (string/array), as_object_mut fails and this internal invariant error is raised. It indicates a bug or unexpected shape in content-part serialization, not user input per se.

Source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/openai/openai_client.rs:211

                            "data:{};base64,{}",
                            media.mime_type_as_ok()?,
                            b64_media.base64
                        ),
                        "filename": "document.pdf"
                    })),
                },
                baml_types::BamlMediaType::Video => {
                    anyhow::bail!(
                        "BAML internal error (openai-responses): video is not yet supported by OpenAI Responses API"
                    );
                }
            }
        }
        ChatMessagePart::WithMeta(inner_part, metadata) => {
            let mut content = responses_content_part(inner_part, role, allowed_metadata)?;
            {
                let content_object = content.as_object_mut().ok_or_else(|| {
                    anyhow::anyhow!(
                        "BAML internal error (openai-responses): content part must be an object"
                    )
                })?;
                for (key, value) in metadata {
                    if allowed_metadata.is_allowed(key) {
                        content_object.insert(key.clone(), value.clone());
                    }
                }
            }
            Ok(content)
        }
    }
}

impl ProviderStrategy {
    fn get_endpoint(&self, base_url: &str, is_completion: bool) -> String {
        match self {
            ProviderStrategy::ResponsesApi => format!("{base_url}/responses"),

View on GitHub (pinned to bd85ce9dee)

Solutions

Upgrade or downgrade BAML to a version where Responses API content-part serialization returns JSON objects
Remove custom metadata attached to content parts and retry
Report the failing prompt/client config to BAML as an internal bug with a repro
Fall back to the chat completions provider strategy

Example fix

// before: metadata on a part that serializes to a string
{{part.with_meta(provider_metadata: {cache_control: ...})}}
// after: use a part type that serializes to an object, or drop metadata
{{part}}

Defensive patterns

Strategy: try-catch

Try / catch

// Rust
match client.call(prompt).await {
    Err(e) if e.to_string().contains("content part must be an object") => {
        // retry without provider metadata, or report BAML bug
    }
    other => other?,
}

Prevention

Only attach metadata supported by the current BAML version
Test prompts with metadata on a staging client before production
Report persistent occurrences to BAML with the exact prompt and client config

When it happens

Trigger: A ChatMessagePart::WithMeta whose inner part serializes to a non-object JSON value, so metadata insertion via as_object_mut fails while building the Responses API request body.

Common situations: BAML internal bug after changes to content-part serialization; custom metadata attached to a part whose converted form is a plain string. Users hit this only through the library producing an invalid intermediate shape.

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