BoundaryML/baml · error · anyhow::Error

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

Error message

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

What it means

Audio media in the OpenAI client must be resolved to base64 before provider conversion; a BamlMediaContent::File variant reaching to_media_message indicates the resolution stage was skipped. The client bails because it cannot inline a file reference into the input_audio payload.

Solutions

Resolve the audio file to base64 before calling the client (force_to_base64 / to_base64)
Pass audio as base64 data or a URL with a usable extension instead of a file reference
Report as a BAML bug if the standard runtime produced an unresolved file

Example fix

// before
let audio = BamlAudio::from_file("speech.mp3");
// after
let audio = BamlAudio::from_file("speech.mp3").to_base64()?;

Defensive patterns

Strategy: validation

Validate before calling

// resolve file-backed audio before the client call
if (audio.content.kind === "file") {
  audio = await audio.to_base64();
}

Type guard

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

Prevention

Convert audio files to base64 before constructing media for SDK calls
Rely on BAML's automatic media resolution rather than manual media objects
Add a preflight assertion that no File content remains before provider conversion

When it happens

Trigger: Audio media whose content is BamlMediaContent::File when building the OpenAI chat completions body (file never converted to Base64).

Common situations: Constructing BamlAudio from a local file path via the SDK without calling base64 conversion, or a runtime bug where file-backed audio bypassed media resolution.

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

Appendix: source

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

                        let extension = match media.mime_type.as_deref() {
                            Some(mime) => mime,
                            None => match extension {
                                Some(ext) => ext,
                                None => anyhow::bail!("BAML internal error (openai): audio url has no extension and no mime type"),
                            },
                        };

                        let format_str = match extension {
                            "mpeg" => "mp3",
                            other => other,
                        };
                        content.insert(
                            payload_key.into(),
                            json!({ "data": url_content.url, "format": format_str }),
                        );
                    }
                    BamlMediaContent::File(_) => {
                        anyhow::bail!(
                            "BAML internal error (openai): audio file should have been resolved to base64, not processed directly."
                        );
                    }
                }
            }
            BamlMediaType::Pdf => {
                let type_value = "file";
                let payload_key = "file";
                content.insert("type".into(), json!(type_value));

                match &media.content {
                    BamlMediaContent::Url(url_content) => {
                        // For URLs, we need to resolve them to base64 first
                        content.insert(
                            payload_key.into(),
                            json!({
                                "type": "input_file",
                                "file_url": url_content.url,

View on GitHub (pinned to bd85ce9dee)