baml.media.image.from_url expects a string argument at {:?}

Error message

baml.media.image.from_url expects a string argument at {:?}

What it means

Thrown when `baml.media.image.from_url` is called with exactly one argument, but that argument is not a String. The builtin matches the single argument against BamlValueWithMeta::String and bails on any other variant (int, media, class, null, etc.).

Source

Thrown at engine/baml-compiler/src/thir/interpret.rs:2724

async fn evaluate_builtin_function(
    fn_name: &str,
    args: &[BamlValueWithMeta<ExprMetadata>],
    type_args: &[baml_types::TypeIR],
    meta: &ExprMetadata,
) -> Result<BamlValueWithMeta<ExprMetadata>> {
    match fn_name {
        "baml.media.image.from_url" => {
            if args.len() != 1 {
                bail!(
                    "baml.media.image.from_url expects 1 argument, got {} at {:?}",
                    args.len(),
                    meta.0
                );
            }
            let url = match &args[0] {
                BamlValueWithMeta::String(s, _) => s.clone(),
                _ => bail!(
                    "baml.media.image.from_url expects a string argument at {:?}",
                    meta.0
                ),
            };
            Ok(BamlValueWithMeta::Media(
                baml_types::BamlMedia::url(baml_types::BamlMediaType::Image, url, None),
                meta.clone(),
            ))
        }
        "baml.fetch_as" => {
            if args.len() != 1 {
                bail!(
                    "baml.fetch_as expects 1 argument (url), got {} at {:?}",
                    args.len(),
                    meta.0
                );
            }
            if type_args.len() != 1 {

View on GitHub (pinned to bd85ce9dee)

Solutions

Pass the URL as a plain string: baml.media.image.from_url("https://...")
If you already have a Media value, use it directly instead of re-wrapping it in from_url
Ensure the variable holding the URL is typed/annotated as string and is non-null
Validate/parse the URL source upstream so the argument is guaranteed to be a string

Example fix

// before (BAML)
let img = baml.media.image.from_url(existingMedia);
// after
let img = existingMedia;  // or baml.media.image.from_url("https://example.com/img.png")

Defensive patterns

Strategy: type-guard

Validate before calling

// validate argument before calling the builtin
if (typeof url !== 'string') {
  throw new Error(`from_url needs a string url, got ${typeof url}`);
}

Type guard

const isString = (v: unknown): v is string => typeof v === 'string';

Try / catch

try {
  img = evaluate(call);
} catch (e) {
  if (String(e).includes('baml.media.image.from_url expects a string argument')) {
    // pass url string directly or reuse existing Media value
  }
  throw e;
}

Prevention

Never pass Media objects back into from_url; use them directly
Ensure url fields are typed string and non-null
Validate URL source values (config/JSON) before use

When it happens

Trigger: Passing a non-string to baml.media.image.from_url, e.g. a previously constructed Media value, a number, or a value read from JSON that arrived typed as something other than string.

Common situations: Passing an existing image/media object instead of a URL string, a variable that was assigned an int ID rather than the URL, or a null when the URL field was missing from config/JSON.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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