BoundaryML/baml · error · anyhow::Error

Cannot convert file media to user facing media

Error message

Cannot convert file media to user facing media

What it means

When converting a BamlMedia whose content came from a local File into a UserFacingBamlMedia (the representation exposed to users in results), BAML refuses because file-based media has no URL or base64 payload to expose. This is an intentional bail, not an internal bug.

Solutions

  1. Load media as base64 or URL explicitly instead of a file reference when you need the user-facing form
  2. Read the file yourself and pass base64: media = base64.b64encode(open(path,'rb').read()).decode()
  3. Keep the original BamlMedia object rather than converting to user-facing media

Example fix

// before
user_media = result.media.to_user_facing()  # raises for file media
// after
import base64
media = baml.Image(base64=base64.b64encode(open('img.png','rb').read()).decode())
user_media = result.media.to_user_facing()
Defensive patterns

Strategy: type-guard

Validate before calling

def is_file_media(m):
    return getattr(m, 'url', None) is None and getattr(m, 'base64', None) is None

Type guard

def user_facing_available(media) -> bool:
    return not (hasattr(media, 'file') and media.file and not media.base64 and not media.url)

Try / catch

try:
    uf = media.to_user_facing()
except Exception:
    uf = load_as_base64(media.file_path)

Prevention

When it happens

Trigger: Accessing `.media`/user-facing representation of an image/audio/pdf that was loaded with `baml.markdown`-style file references (BamlMediaContent::File) instead of a URL or inline base64.

Common situations: Reading media attached via a file path from a function result and trying to serialize or inspect it as user-facing content; occurs after round-tripping media into a response object.

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

Appendix: source

Thrown at engine/language_client_python/src/types/media_repr.rs:61

        }
    }
}

impl TryInto<UserFacingBamlMedia> for &BamlMedia {
    type Error = anyhow::Error;

    fn try_into(self) -> Result<UserFacingBamlMedia> {
        Ok(UserFacingBamlMedia {
            mime_type: self.mime_type.clone(),
            content: match &self.content {
                BamlMediaContent::Url(url) => UserFacingBamlMediaContent::Url {
                    url: url.url.clone(),
                },
                BamlMediaContent::Base64(base64) => UserFacingBamlMediaContent::Base64 {
                    base64: base64.base64.clone(),
                },
                BamlMediaContent::File(_) => {
                    anyhow::bail!("Cannot convert file media to user facing media")
                }
            },
        })
    }
}

/// This function is used for Pydantic compatibility in three ways:
///
///   - allows constructing Pydantic models containing a BAML media instance
///   - allows FastAPI requests to deserialize BAML media instances in JSON format
///   - allows serializing BAML media instances in JSON format
///
/// Ideally this belongs in baml_py.internal_monkeypatch, so that we can get
/// ruff-based type checking, but this depends on the pydantic libraries, so we
/// can't implement this in internal_monkeypatch without adding a hard dependency
/// on pydantic. And we don't want to do _that_, because that will make it harder
/// to implement output_type python/vanilla in the future.
///

View on GitHub (pinned to bd85ce9dee)