{"record":{"id":"40231ecd14b191a3","repo":"BoundaryML/baml","slug":"baml-internal-error-openai-responses-local-pdf-files-are-not","errorCode":null,"errorMessage":"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: {:?}","messagePattern":"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: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"engine/baml-runtime/src/internal/llm_client/primitive/openai/openai_client.rs","lineNumber":185,"sourceCode":"                                \"data\": b64_media.base64,\n                                \"format\": format\n                            }\n                        }))\n                    }\n                    _ => {\n                        anyhow::bail!(\n                            \"BAML internal error (openai-responses): audio must be base64 encoded for Responses API\"\n                        );\n                    }\n                },\n                baml_types::BamlMediaType::Pdf => match &media.content {\n                    baml_types::BamlMediaContent::Url(url_content) => Ok(json!({\n                        \"type\": \"input_file\",\n                        \"file_url\": url_content.url,\n                        \"filename\": \"document.pdf\"\n                    })),\n                    baml_types::BamlMediaContent::File(file_content) => {\n                        anyhow::bail!(\n                            \"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: {:?}\",\n                            file_content.relpath\n                        );\n                    }\n                    baml_types::BamlMediaContent::Base64(b64_media) => Ok(json!({\n                        \"type\": \"input_file\",\n                        \"file_data\": format!(\n                            \"data:{};base64,{}\",\n                            media.mime_type_as_ok()?,\n                            b64_media.base64\n                        ),\n                        \"filename\": \"document.pdf\"\n                    })),\n                },\n                baml_types::BamlMediaType::Video => {\n                    anyhow::bail!(\n                        \"BAML internal error (openai-responses): video is not yet supported by OpenAI Responses API\"\n                    );","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/baml-runtime/src/internal/llm_client/primitive/openai/openai_client.rs#L167-L203","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: local PDF on a Responses API client\npdf { file \"./reports/q3.pdf\" }\n\n// after: remote URL or base64\npdf { url \"https://example.com/q3.pdf\" }\n// or\npdf { b64 \"JVBERi0xLjcK...\" }","handlingStrategy":"validation","validationCode":"match &pdf.content {\n    BamlMediaContent::Url(_) | BamlMediaContent::Base64(_) => {},\n    BamlMediaContent::File(f) => panic!(\n        \"local PDF {:?} unsupported by Responses API; use url or b64\", f.relpath\n    ),\n}","typeGuard":"fn pdf_is_sendable(media: &BamlMedia) -> bool {\n    matches!(media.content, BamlMediaContent::Url(_) | BamlMediaContent::Base64(_))\n}","tryCatchPattern":"match result {\n    Err(e) if e.to_string().contains(\"Local PDF files are not supported\") => {\n        // read the file, base64 it, and rebuild the prompt with b64 media\n    }\n    r => r?,\n}","preventionTips":["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."],"tags":["openai","responses-api","pdf","local-file","rust"],"backgroundTag":"unsupported-operation","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}