BoundaryML/baml · error · anyhow::Error

BAML internal error (openai-responses): image file should ha

Error message

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

What it means

While building an `input_image` content part for the OpenAI Responses API, BAML encountered an image whose content is still `BamlMediaContent::File` — a local file reference. By contract, file-based media must be resolved (loaded into URL or base64 form) earlier in the media pipeline, so hitting this arm means an unresolved local file image reached the provider-body builder. It is an internal invariant check, indicating the media-resolution step was skipped or failed silently.

Source

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

            // For assistant role, we only support text outputs in Responses API.
            if role == "assistant" {
                anyhow::bail!(
                    "BAML internal error (openai-responses): assistant messages must be text; media not supported for assistant in Responses API"
                );
            }
            match media.media_type {
                baml_types::BamlMediaType::Image => {
                    let image_url = match &media.content {
                        baml_types::BamlMediaContent::Url(url_content) => url_content.url.clone(),
                        baml_types::BamlMediaContent::Base64(b64_media) => {
                            format!(
                                "data:{};base64,{}",
                                media.mime_type_as_ok()?,
                                b64_media.base64
                            )
                        }
                        baml_types::BamlMediaContent::File(_) => {
                            anyhow::bail!(
                                "BAML internal error (openai-responses): image file should have been resolved, not processed directly."
                            );
                        }
                    };
                    Ok(json!({
                        "type": "input_image",
                        "detail": "auto",
                        "image_url": image_url
                    }))
                }
                baml_types::BamlMediaType::Audio => match &media.content {
                    baml_types::BamlMediaContent::Base64(b64_media) => {
                        let mime_type = media.mime_type_as_ok()?;
                        let format = mime_type.strip_prefix("audio/").unwrap_or(&mime_type);
                        Ok(json!({
                            "type": "input_audio",
                            "input_audio": {
                                "data": b64_media.base64,

View on GitHub (pinned to bd85ce9dee)

Solutions

Inline the image as base64 (b64) or supply a remote URL instead of a local file reference, both of which the Responses API path supports.
Ensure media goes through BAML's normal resolution (let BAML load files at runtime) rather than constructing ChatMessagePart::File manually.
Verify the image path resolves in your runtime environment; a failed resolution can leave the File variant in place.
If you need direct local-file support for Responses API images, file an issue; currently only Url and Base64 variants are handled.

Example fix

// before: local file reference in a Responses API client
image { file "./cat.png" }

// after: base64-inline or URL the image
image { b64 "iVBORw0KGgo..." }
// or
image { url "https://example.com/cat.png" }

Defensive patterns

Strategy: validation

Validate before calling

// before calling the function, ensure images are url or b64, not local files
assert!(matches!(img.content, BamlMediaContent::Url(_) | BamlMediaContent::Base64(_)),
        "image must be url or base64 for Responses API");

Type guard

fn image_is_resolved(media: &BamlMedia) -> bool {
    matches!(media.content, BamlMediaContent::Url(_) | BamlMediaContent::Base64(_))
}

Try / catch

match result {
    Err(e) if e.to_string().contains("should have been resolved") => {
        // re-load the media as base64 and rebuild the request
    }
    r => r?,
}

Prevention

Always pass images via url or b64 when using a Responses-API client.
Let BAML's runtime load file media; avoid constructing File content parts manually.
Verify file paths resolve in the deployment environment (container vs local).

When it happens

Trigger: Passing an image via `image(...)` with a local file path to a function whose client uses the OpenAI Responses API, in a context where BAML's file-resolution stage did not run (openai_client.rs:149 bails on `BamlMediaContent::File(_)` inside the Image match).

Common situations: Referencing a local image file path in a prompt sent to a Responses-API client; a custom/integration path (e.g. programmatic API building chat parts directly) that bypasses BAML's file loading; environment differences where a file that normally resolves at runtime wasn't loaded.

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