BoundaryML/baml · error · anyhow::Error

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

Error message

BAML internal error (openai): Pdf file should have been resolved to base64 before this stage.

What it means

PDF media must be resolved to base64 before reaching the OpenAI provider converter. A BamlMediaContent::File variant in to_media_message means resolution was skipped, so BAML bails. The unused media_file binding underlines it is an unexpected state.

Solutions

Convert the PDF to base64 before invoking the client (use BAML's media base64 resolution)
Pass the PDF as base64 data rather than a file reference
If produced by the normal BAML runtime, file a bug with a repro

Example fix

// before
let pdf = BamlMedia::file("doc.pdf");
// after
let pdf = BamlMedia::file("doc.pdf").to_base64()?;

Defensive patterns

Strategy: validation

Validate before calling

// resolve PDFs before invoking an openai client
if (pdf.content.kind === "file") {
  pdf = await pdf.to_base64();
}

Type guard

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

Prevention

Embed PDFs as base64 in prompts or resolve files through BAML's media APIs
Assert media is Base64-resolved in integration tests before provider calls
Avoid hand-constructing BamlMedia::file in SDK code

When it happens

Trigger: PDF media whose content is still File (not Base64) when the OpenAI chat completions request body is built.

Common situations: SDK users constructing BamlMedia::file without converting to base64, or embedding a PDF file path in a prompt where the automatic media-resolution stage did not execute.

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

Appendix: source

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

                            json!({
                                "type": "input_file",
                                "file_url": url_content.url,
                                "filename": "document.pdf"
                            }),
                        );
                    }
                    BamlMediaContent::Base64(b64_media) => {
                        content.insert(
                            payload_key.into(),
                            json!({
                                "filename": "document.pdf",
                                "file_data": format!("data:{};base64,{}", media.mime_type_as_ok()?, b64_media.base64)
                            }),
                        );
                    }
                    BamlMediaContent::File(media_file) => {
                        // For files, we need to resolve them to base64 first
                        anyhow::bail!(
                            "BAML internal error (openai): Pdf file should have been resolved to base64 before this stage."
                        );
                    }
                }
            }
            BamlMediaType::Video => {
                // OpenAI video is only supported on the Realtime API (/v1/realtime), not on chat completions
                anyhow::bail!(
                    "Video input is only supported on OpenAI's Realtime API (/v1/realtime), not on chat completions. \
                    Consider extracting frames from the video as images instead. \
                    See: https://platform.openai.com/docs/guides/realtime"
                );
            }
        }
        Ok(content)
    }

    fn role_to_message(

View on GitHub (pinned to bd85ce9dee)