What causes "Failed to parse URL: {}" in BoundaryML/baml?

Fix the media URL so it is a fully valid absolute URL (scheme + host)

Failed to parse URL

Error message

Failed to parse URL: {}

What it means

When a proxy is configured, BAML rewrites the media URL by appending the target URL's path to the proxy base; the URL failed to parse with the url crate, so the path cannot be extracted and the request aborts.

Solutions

Fix the media URL so it is a fully valid absolute URL (scheme + host)
URL-encode special characters (spaces, unicode) before passing the URL
Check that any templating/env substitution produced the intended URL rather than a literal placeholder
If you don't need the proxy, unset the proxy_url configuration

Example fix

// before
url "example.com/doc pdf.pdf"
// after
url "https://example.com/doc%20pdf.pdf"

Defensive patterns

Strategy: validation

Validate before calling

function isValidUrl(u) {
  try { const parsed = new URL(u); return !!parsed.protocol && !!parsed.hostname; }
  catch { return false; }
}
if (!isValidUrl(mediaUrl)) throw new Error(`Invalid media URL: ${mediaUrl}`);

Type guard

const isHttpUrl = (s) => { try { const u = new URL(s); return u.protocol === 'http:' || u.protocol === 'https:'; } catch { return false; } };

Try / catch

try {
  await runBamlFn();
} catch (e) {
  if (/Failed to parse URL/.test(String(e.message))) {
    console.error('Malformed media URL passed to BAML:', mediaUrl);
  }
  throw e;
}

Prevention

Validate URLs with a URL parser before passing them to BAML
Encode spaces/unicode with encodeURIComponent in path segments
Check templating/env substitution isn't leaking literal placeholders into URLs

When it happens

Trigger: A proxy_url is set in the runtime context and media_url.url is malformed (missing scheme, invalid characters, whitespace) so url::parse fails.

Common situations: Typo'd media URLs (missing https://); URLs with unescaped spaces or non-ASCII characters; env-var proxy settings accidentally injected into the URL field; template variables not rendered.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

Thrown at engine/baml-runtime/src/internal/llm_client/traits/mod.rs:834

            return Some((mime_type, base64));
        }
    }

    None
}

async fn fetch_with_proxy(
    url: &str,
    proxy_url: Option<&str>,
) -> Result<reqwest::Response, anyhow::Error> {
    let client = reqwest::Client::new();

    let request = if let Some(proxy) = proxy_url {
        let new_proxy_url = format!(
            "{}{}",
            proxy,
            url.parse::<url::Url>()
                .map_err(|e| anyhow::anyhow!("Failed to parse URL: {}", e))?
                .path()
        );
        client.get(new_proxy_url).header("baml-original-url", url)
    } else {
        client.get(url)
    };

    let response = request.send().await?;
    Ok(response)
}

#[cfg(test)]
mod tests_scrub {
    use std::collections::HashMap;

    use baml_types::BamlMap;
    use serde_json::json;

View on GitHub (pinned to bd85ce9dee)