BoundaryML/baml · error · Error

Audio is not a URL

Error message

Audio is not a URL

What it means

BAML's Audio media object can hold content either as a URL or as base64 data. asUrl() is a narrowing accessor that returns the content only when the audio was constructed from a URL; otherwise it throws to prevent silently returning base64 data as if it were a URL.

Source

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

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

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

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

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

  /**
   * Convert the audio to a JSON representation

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check audio.isUrl() before calling asUrl(), and branch to asBase64() otherwise
2. Construct the Audio from a URL (Audio.fromUrl(...)) when URL access is required
3. Write generic handling that inspects the storage type instead of assuming one

Example fix

// before
const url = audio.asUrl(); // throws for base64 audio
// after
if (audio.isUrl()) {
  const url = audio.asUrl();
} else {
  const [b64, mediaType] = audio.asBase64();
}

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

const isUrlAudio = (a) => a.isUrl();

try { const url = audio.asUrl(); }
catch { const [b64, mt] = audio.asBase64(); /* fallback path */ }

When it happens

Trigger: Calling audio.asUrl() on an Audio created with fromBase64 (or from any non-URL source such as a file/raw media), where isUrl() is false.

Common situations: Receiving Audio objects from a BAML client/LLM response and assuming they are always URL-backed; mixing base64-embedded media (common when passing raw bytes to models) with URL-based media handling code.

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 base64
• Image is not a URL
• 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/1f70433be2b76555. Report an issue: GitHub.