BoundaryML/baml · error · anyhow::Error

BAML internal error (openai-responses): Local PDF files are

Error message

BAML internal error (openai-responses): Local PDF files are not supported by OpenAI Responses API - use file_url for remote files or upload file and use file_id. File path: {:?}

What it means

When serializing a PDF media part for the OpenAI Responses API, BAML found a local file reference (`BamlMediaContent::File`). The Responses API only accepts PDFs as a remote `file_url` or as base64 `file_data`; a local file path cannot be sent directly, so BAML fails with the file's relpath in the message. Unlike images, there is no automatic resolution to base64 for PDF files in this path.

Source

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

                                "data": b64_media.base64,
                                "format": format
                            }
                        }))
                    }
                    _ => {
                        anyhow::bail!(
                            "BAML internal error (openai-responses): audio must be base64 encoded for Responses API"
                        );
                    }
                },
                baml_types::BamlMediaType::Pdf => match &media.content {
                    baml_types::BamlMediaContent::Url(url_content) => Ok(json!({
                        "type": "input_file",
                        "file_url": url_content.url,
                        "filename": "document.pdf"
                    })),
                    baml_types::BamlMediaContent::File(file_content) => {
                        anyhow::bail!(
                            "BAML internal error (openai-responses): Local PDF files are not supported by OpenAI Responses API - use file_url for remote files or upload file and use file_id. File path: {:?}",
                            file_content.relpath
                        );
                    }
                    baml_types::BamlMediaContent::Base64(b64_media) => Ok(json!({
                        "type": "input_file",
                        "file_data": format!(
                            "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"
                    );

View on GitHub (pinned to bd85ce9dee)

Solutions

Replace the local file with a remote URL (`pdf { url "https://..." }`) so it maps to `input_file.file_url`.
Base64-encode the PDF and use `pdf { b64 ... }` so it maps to `input_file.file_data`.
Upload the file to OpenAI's Files API and reference it per OpenAI's file_id flow if you prefer server-side storage.
If local PDF support is required, switch to a client/provider strategy that resolves files (e.g. standard Chat Completions where applicable) or file an upstream feature request.

Example fix

// before: local PDF on a Responses API client
pdf { file "./reports/q3.pdf" }

// after: remote URL or base64
pdf { url "https://example.com/q3.pdf" }
// or
pdf { b64 "JVBERi0xLjcK..." }

Defensive patterns

Strategy: validation

Validate before calling

match &pdf.content {
    BamlMediaContent::Url(_) | BamlMediaContent::Base64(_) => {},
    BamlMediaContent::File(f) => panic!(
        "local PDF {:?} unsupported by Responses API; use url or b64", f.relpath
    ),
}

Type guard

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

Try / catch

match result {
    Err(e) if e.to_string().contains("Local PDF files are not supported") => {
        // read the file, base64 it, and rebuild the prompt with b64 media
    }
    r => r?,
}

Prevention

Host PDFs at a URL or base64-inline them for Responses-API clients.
Never use local file paths for PDFs with OpenAI Responses API strategies.
Consider uploading PDFs to OpenAI's Files API for reusable file_id references.

When it happens

Trigger: Using `pdf { file "./doc.pdf" }` (local path) in a prompt sent through a client configured for the OpenAI Responses API; the `File` arm in the Pdf match bails (openai_client.rs:184-189) while Url and Base64 arms succeed.

Common situations: Pointing a BAML prompt at a local PDF while using a Responses-API model (e.g. GPT-4o document input via Responses); migrating prompts that used local PDFs with other providers; forgetting that `file_url` in BAML's Responses path maps to a remote URL, not a local path.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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