BoundaryML/baml · error

Requested media of MIME type '{}' but fetched '{}' from URL

Error message

Requested media of MIME type '{}' but fetched '{}' from URL {}. Please ensure the URL points to the correct file or update the mime_type in BAML.

What it means

BAML validates that the MIME type it infers from fetched media matches the mime_type declared in the BAML schema. When a URL download's inferred type differs from the expected type (e.g. image declared but server returns HTML), process_media bails to prevent sending the wrong content to the model.

Source

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

                    None
                }
            } else {
                match part.media_type {
                    BamlMediaType::Pdf => Some("application/pdf".to_string()),
                    _ => None,
                }
            };

            if let Some(expected) = &expected_mime_type {
                // we accept subtype matches (e.g. image/jpeg starts_with image/)
                let mismatch = if expected.contains('/') {
                    &inferred_mime_type != expected
                } else {
                    !inferred_mime_type.starts_with(expected)
                };

                if mismatch {
                    anyhow::bail!(
                        "Requested media of MIME type '{}' but fetched '{}' from URL {}. Please ensure the URL points to the correct file or update the mime_type in BAML.",
                        expected,
                        inferred_mime_type,
                        media_url.url
                    );
                }
            }

            Ok(BamlMedia::base64(
                part.media_type,
                if render_settings.as_shell_commands {
                    format!("$(curl -L '{}' | base64)", media_url.url)
                } else {
                    base64
                },
                Some(part.mime_type.clone().unwrap_or(inferred_mime_type)),
            ))
        }

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Fix the URL so it actually serves the declared media type (curl -I to check Content-Type)
2. Update the mime_type in the BAML file to match what the URL serves
3. If using a proxy/CDN, ensure it passes through correct Content-Type headers
4. Download the file locally and send base64 with an explicit data: URL prefix instead

Example fix

// before
image my_img
  url "https://example.com/report.pdf"
// after
image my_img
  url "https://example.com/photo.jpg"

async function assertUrlServes(url, expectedPrefix) {
  const res = await fetch(url, { method: 'HEAD' });
  const ct = res.headers.get('content-type') || '';
  if (!res.ok || !ct.startsWith(expectedPrefix)) throw new Error(`URL ${url} serves '${ct}', expected '${expectedPrefix}'`);
}
await assertUrlServes(mediaUrl, 'image/');

try {
  await runBamlFn();
} catch (e) {
  if (/Requested media of MIME type/.test(String(e.message))) {
    console.warn(`Media content mismatch at: ${e.message.match(/from URL (\S+)/)?.[1]}`);
  }
  throw e;
}

When it happens

Trigger: process_media_urls downloads a URL for media whose declared mime_type (exact match for images, prefix match otherwise) differs from the inferred type from response bytes.

Common situations: URL points to an HTML login/error page instead of the image; CDN serves a generic content type; file was replaced or moved; mime_type in BAML file outdated after re-uploading a different format.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Could not determine mime type for PDF input. Only applicatio
• baml.media.image.from_url expects 1 argument, got {} at {:?}
• baml.media.image.from_url expects a string argument at {:?}
• baml.fetch_as: HTTP request failed: HTTP {} Body: {} at {:?}
• Could not unify Media with {:?}

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