BoundaryML/baml · error

BAML internal error (Anthropic): file should have been resol

Error message

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

What it means

When converting BAML media (images/audio) into Anthropic message content, only Base64 or Url content variants are valid at request-build time. A File variant means the media was never pre-processed (resolved/uploaded to base64) as required, so BAML bails with this internal invariant error.

Source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/anthropic/anthropic_client.rs:376

    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.media_type {
            baml_types::BamlMediaType::Audio | baml_types::BamlMediaType::Image => {
                // Standard handling for audio and images
                match &media.content {
                    BamlMediaContent::Base64(data) => {
                        content.insert("type".into(), media.media_type.to_string().into());
                        let mut source = serde_json::Map::new();
                        source.insert("type".into(), "base64".into());
                        source.insert("media_type".into(), media.mime_type_as_ok()?.into());
                        source.insert("data".into(), data.base64.clone().into());
                        content.insert("source".into(), source.into());
                    }
                    BamlMediaContent::File(_) => {
                        anyhow::bail!(
                            "BAML internal error (Anthropic): file should have been resolved to base64"
                        )
                    }
                    BamlMediaContent::Url(url) => {
                        content.insert("type".into(), media.media_type.to_string().into());
                        let mut source = serde_json::Map::new();
                        source.insert("type".into(), "url".into());
                        source.insert("url".into(), url.url.clone().into());
                        content.insert("source".into(), source.into());
                    }
                }
            }
            baml_types::BamlMediaType::Pdf => {
                // Anthropic supports Pdf inline as Base64 or URL (max 32 MB, 100 pages)
                match &media.content {
                    BamlMediaContent::Base64(data) => {
                        content.insert("type".into(), "document".into());
                        let mut source = serde_json::Map::new();

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Pass media as a base64 string or a URL instead of a raw file path/blob
  2. Ensure the BAML runtime can run its media-resolution subprocess (enable file-to-base64 conversion)
  3. Check logs from the media resolution step for silent conversion failures
  4. Upgrade BAML — file resolution handling has been improved in newer versions

Example fix

// before
await b.functions.Describe({ image: b.Image.fromPath('./img.png') }); // file never resolved
// after
const data = fs.readFileSync('./img.png');
await b.functions.Describe({ image: b.Image.fromBase64('image/png', data.toString('base64')) });
Defensive patterns

Strategy: validation

Validate before calling

function assertMediaResolved(media) {
  if (media && media.file != null && media.base64 == null && media.url == null)
    throw new Error('Media must be base64 or url before sending to Anthropic');
}

Type guard

const isResolvedMedia = (m) => m != null && (typeof m.base64 === 'string' || typeof m.url === 'string');

Try / catch

try {
  return await b.functions.Describe({ image });
} catch (e) {
  if (/file should have been resolved to base64/.test(String(e))) {
    throw new Error('Convert file media to base64 before calling Anthropic-backed functions');
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing an image/media whose BamlMediaContent is File(_) into to_media_message for the Anthropic client — i.e. media supplied as a raw file path/blob that the media-resolution pipeline failed to convert to base64 before the request.

Common situations: Media loading/subprocessing step skipped or failed silently (e.g. node subprocess disabled); passing a very large file that failed conversion; calling the API at a layer that bypasses BAML's media resolution; client/server serialization dropping the resolved content.

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