BoundaryML/baml · error · Error

Image is not a URL

Error message

Image is not a URL

What it means

BAML's Image object stores content either as a URL or base64. asUrl() narrows to the URL case and throws when the image is not URL-backed, protecting callers from receiving base64 data mistaken for a URL.

Source

Thrown at engine/language_client_typescript/typescript_src/image.ts:69

    const response = await fetch(url);
    const blob = await response.blob();
    return BamlImage.fromBlob(blob);
  }

  /**
   * Check if the image is stored as a URL
   */
  isUrl(): boolean {
    return this.type === 'url';
  }

  /**
   * Get the URL of the image if it's stored as a URL
   * @throws Error if the image is not stored as a URL
   */
  asUrl(): string {
    if (!this.isUrl()) {
      throw new Error('Image is not a URL');
    }
    return this.content;
  }

  /**
   * Get the base64 data and media type if the image is stored as base64
   * @returns [base64Data, mediaType]
   * @throws Error if the image is not stored as base64
   */
  asBase64(): [string, string] {
    if (this.type !== 'base64') {
      throw new Error('Image is not base64');
    }
    return [this.content, this.mediaType || ''];
  }

  /**
   * Convert the image to a JSON representation

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Guard with image.isUrl() before calling asUrl()
2. Create the Image with Image.fromUrl(...) if URL access is required
3. Handle both storage types explicitly (branch to asBase64() when not a URL)

Example fix

// before
const url = image.asUrl(); // throws for base64 image
// after
const src = image.isUrl() ? image.asUrl() : `data:${image.asBase64()[1]};base64,${image.asBase64()[0]}`;

if (!image.isUrl()) { /* handle base64 branch */ }

const isUrlImage = (i) => i.isUrl();

try { const url = image.asUrl(); }
catch { const [b64, mt] = image.asBase64(); }

When it happens

Trigger: Calling image.asUrl() on an Image built from base64 (fromBase64) or another non-URL source, so isUrl() returns false.

Common situations: Rendering image URLs in UI code while the model returned inline base64 images; passing config-loaded images (often base64) into code that assumes URL storage.

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

• Audio is not a URL
• Image is not base64
• Pdf is not a URL
• BAML internal error (AWSBedrock): file should have been reso
• BAML internal error (AWSBedrock): Pdf file should have been

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