What causes "Image is not base64" in BoundaryML/baml?

Check image.type === 'base64' before calling asBase64()

BoundaryML/baml · error · Error

Image is not base64

Error message

Image is not base64

What it means

BAML's Image.asBase64() returns [base64Data, mediaType] only when the image content is stored as base64. URL-backed images have no inline payload, so the method throws rather than returning empty/invalid data.

Source

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

  /**
   * 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
   */
  toJSON(): { url: string } | { base64: string; media_type: string } {
    if (this.type === 'url') {
      return { url: this.content };
    }
    return {
      base64: this.content,
      media_type: this.mediaType || '',
    };
  }
}

View on GitHub (pinned to bd85ce9dee)

Solutions

Check image.type === 'base64' before calling asBase64()
Fetch the image from its URL and encode to base64 when bytes are needed
Use Image.fromBase64(...) at construction time if downstream code requires base64

Example fix

// before
const [b64, mt] = image.asBase64(); // throws for URL image
// after
if (image.type === 'base64') {
  const [b64, mt] = image.asBase64();
} else {
  const res = await fetch(image.asUrl());
  const b64 = Buffer.from(await res.arrayBuffer()).toString('base64');
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (image.type !== 'base64') { /* fetch URL and encode */ }

Type guard

const isBase64Image = (i) => i.type === 'base64';

Try / catch

try { const [b64, mt] = image.asBase64(); }
catch { const bytes = await (await fetch(image.asUrl())).arrayBuffer(); }

Prevention

Check type === 'base64' before asBase64()
Fetch-and-encode helper for URL images
Document expected storage type at API boundaries

When it happens

Trigger: Calling image.asBase64() on an Image whose type is 'url' (created via fromUrl), i.e. this.type !== 'base64'.

Common situations: Pipelines that inline images into API payloads (needing base64) but receive URL-referenced images from model responses or user configuration.

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

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