BoundaryML/baml · error · anyhow::Error

BAML internal error (openai): image file should have been…

Error message

BAML internal error (openai): image file should have been resolved, not processed directly.

What it means

In to_media_message, image media must already have been resolved to base64 (BamlMediaContent::Base64) before provider conversion. Encountering BamlMediaContent::File means a file-backed image reached the OpenAI client unresolved, so it bails with this internal error.

Solutions

  1. Resolve the image to base64 before handing it to the client (use BAML media resolution APIs: .to_base64 / force_to_base64)
  2. Pass a URL or base64 data source instead of a raw file reference
  3. If using the BAML runtime normally, report as a bug — files should be resolved automatically

Example fix

// before (Rust/SDK)
let media = BamlImage::from_file("cat.png"); // unresolved file
// after
let media = BamlImage::from_file("cat.png").to_base64()?; // resolved
Defensive patterns

Strategy: validation

Validate before calling

// before calling the client with an image
if (image.content.kind === "file") {
  image = await image.to_base64();
}

Type guard

fn is_base64_image(m: &BamlMedia) -> bool {
    matches!(m.content, BamlMediaContent::Base64(_))
}

Prevention

When it happens

Trigger: An image media whose content is still a File reference (not resolved to Base64) when building the OpenAI chat completions request body.

Common situations: Passing a local file path as image media in a context where BAML's media resolution stage did not run (custom/programmatic media construction, SDK usage building BamlImage from file manually).

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

            BamlMediaType::Image => {
                let type_value = "image_url";
                let payload_key = "image_url";
                content.insert("type".into(), json!(type_value));

                match &media.content {
                    BamlMediaContent::Url(url_content) => {
                        content.insert(payload_key.into(), json!({ "url": url_content.url }));
                    }
                    BamlMediaContent::Base64(b64_media) => {
                        content.insert(
                            payload_key.into(),
                            json!({
                                "url": format!("data:{};base64,{}", media.mime_type_as_ok()?, b64_media.base64)
                            }),
                        );
                    }
                    BamlMediaContent::File(_) => {
                        anyhow::bail!("BAML internal error (openai): image file should have been resolved, not processed directly.");
                    }
                }
            }
            BamlMediaType::Audio => {
                let type_value = "input_audio";
                let payload_key = "input_audio";
                content.insert("type".into(), json!(type_value));

                match &media.content {
                    BamlMediaContent::Base64(b64_media) => {
                        let mime_type_str = media.mime_type_as_ok()?;
                        // remove "audio/" from the start of the mime type if it exists
                        let mime_type_str = mime_type_str
                            .strip_prefix("audio/")
                            .unwrap_or(mime_type_str.as_str());

                        // note: openai only supports mp3/wav for audio input
                        // but we can still send other formats and allow openai to handle

View on GitHub (pinned to bd85ce9dee)