BoundaryML/baml · error · Error

Image is not a URL

Error message

Image is not a URL

What it means

JavaScript client state guard: asUrl() was called on a BamlImage whose internal type is 'base64', not 'url'. BamlImage is a tagged union of url/base64 representations and each accessor demands its own tag; the guard fires before returning content so callers never misinterpret base64 payload data as a URL.

Solutions

1. Check image.isUrl() before calling asUrl().
2. Use asBase64() when the image stores base64 data.
3. Construct the image with Image.fromUrl when URL access is needed.

Example fix

// before
const url = image.asUrl(); // throws for base64 image
// after
const url = image.isUrl() ? image.asUrl() : null;

if (image.isUrl()) { /* safe to call asUrl */ }

function isUrlImage(image) { return typeof image.isUrl === 'function' && image.isUrl(); }

try {
  const url = image.asUrl();
} catch (e) {
  if (e.message === 'Image is not a URL') { /* fall back to asBase64 */ }
  else throw e;
}

When it happens

Trigger: Calling image.asUrl() on an Image instance created from base64 data.

Common situations: Handling image outputs from vision/LLM calls that return base64 and assuming a URL; mixing up Image.fromUrl vs Image.fromBase64 instances.

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

• Image is not base64
• Audio is not a URL
• Audio is not base64
• Image is not a URL
• Image is not base64

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

Appendix: source

Thrown at engine/language_client_typescript/image.js:68

     */
    static async fromUrlAsync(url) {
        const response = await fetch(url);
        const blob = await response.blob();
        return BamlImage.fromBlob(blob);
    }
    /**
     * Check if the image is stored as a URL
     */
    isUrl() {
        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() {
        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() {
        if (this.type !== 'base64') {
            throw new Error('Image is not base64');
        }
        return [this.content, this.mediaType || ''];
    }
    /**
     * Convert the image to a JSON representation
     */
    toJSON() {

View on GitHub (pinned to bd85ce9dee)