BAML internal error (Vertex): file should have been resolved

Error message

BAML internal error (Vertex): file should have been resolved to base64

What it means

Vertex media messages must already have file-based content resolved to base64 before request construction. If a BamlMedia still holds BamlMediaContent::File at this point, an earlier resolution pass was skipped, so BAML raises this internal-invariant error rather than sending an invalid request.

Source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/vertex/vertex_client.rs:467

}

impl ToProviderMessage for VertexClient {
    fn to_chat_message(
        &self,
        mut content: serde_json::Map<String, serde_json::Value>,
        text: &str,
    ) -> Result<serde_json::Map<String, serde_json::Value>> {
        content.insert("text".into(), json!(text));
        Ok(content)
    }

    fn to_media_message(
        &self,
        mut content: serde_json::Map<String, serde_json::Value>,
        media: &baml_types::BamlMedia,
    ) -> Result<serde_json::Map<String, serde_json::Value>> {
        match &media.content {
            BamlMediaContent::File(_) => anyhow::bail!(
                "BAML internal error (Vertex): file should have been resolved to base64"
            ),
            BamlMediaContent::Url(data) => {
                let mime_type = match &media.mime_type {
                    Some(mime) if !mime.is_empty() => mime.clone(),
                    _ => {
                        // Provide default mime types when none specified
                        match media.media_type {
                            baml_types::BamlMediaType::Video => "video/mp4".to_string(),
                            _ => media.mime_type_as_ok()?,
                        }
                    }
                };
                content.insert(
                    "fileData".into(),
                    json!({
                        "fileUri": data.url,
                        "mimeType": mime_type

View on GitHub (pinned to bd85ce9dee)

Solutions

Ensure media inputs go through BAML's normal resolution pipeline (e.g. baml.* image/url or file inputs are loaded before the request is built)
If constructing media programmatically, convert file content to base64 (BamlMediaContent::Url/Base64) instead of leaving it as File
Verify you're on an up-to-date BAML version; if this reproduces with standard usage, report it as a bug to the BAML maintainers

Defensive patterns

Strategy: try-catch

Try / catch

try {
  return await baml_client.MyImageFunction(input);
} catch (err) {
  if (String(err).includes('file should have been resolved to base64')) {
    // This is an internal invariant: report bug / ensure media went through the loader
    throw new Error('Media was not resolved; ensure images pass through BAML\'s media loading, not raw BamlMedia objects');
  }
  throw err;
}

Prevention

Always construct media inputs via BAML's public API (baml image/file helpers) so files get base64-resolved
Never hand-build BamlMedia with BamlMediaContent::File in custom integrations
Keep BAML runtime and CLI versions in sync; report occurrences as a bug

When it happens

Trigger: Passing an image/audio/file media whose content is still a raw file reference (not base64) when constructing a Vertex request — i.e. the media was not run through BAML's media resolution/loading pipeline.

Common situations: Programmatically constructing BamlMedia objects bypassing BAML's loader, or a bug/early failure in the file-to-base64 resolution stage that wasn't reported earlier.

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