BoundaryML/baml · error · Error

Image is not base64

Error message

Image is not base64

What it means

JavaScript client state guard: asBase64() was called on a BamlImage whose internal type is 'url'. The method contract is to return [base64Data, mediaType]; serving URL text there would silently corrupt downstream payloads, so the wrong-tag check throws instead. Use asUrl(), or fetch and convert the image to base64 first.

Solutions

  1. Check this.type === 'base64' (or equivalent) before calling asBase64().
  2. Use asUrl() for URL-stored images, or fetch the URL and encode to base64 yourself.
  3. Construct with Image.fromBase64 if base64 access is required.

Example fix

// before
const [data, mediaType] = image.asBase64(); // throws for URL image
// after
const [data, mediaType] = image.type === 'base64' ? image.asBase64() : [null, null];
Defensive patterns

Strategy: type-guard

Validate before calling

if (image.type === 'base64') { /* safe to call asBase64 */ }

Type guard

function isBase64Image(image) { return image.type === 'base64'; }

Try / catch

try {
  const [data, mt] = image.asBase64();
} catch (e) {
  if (e.message === 'Image is not base64') { /* use asUrl or fetch+encode */ }
  else throw e;
}

Prevention

When it happens

Trigger: Calling image.asBase64() on an Image instance constructed from a URL (type !== 'base64').

Common situations: Needing raw base64 bytes for an API that requires inline data but holding a remote URL image; confusing which constructor produced the instance.

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/c892dff399d22a11. Report an issue: GitHub.

Appendix: source

Thrown at engine/language_client_typescript/image.js:79

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

View on GitHub (pinned to bd85ce9dee)