BoundaryML/baml · error · Error

Pdf is not base64

Error message

Pdf is not base64

What it means

TypeScript client state guard: asBase64() was called on a BamlPdf whose internal type is 'url'. The method must return [base64Data, mediaType]; handing back URL text would corrupt the payload, so the tag check throws. Use asUrl() or convert the representation first.

Source

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

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

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

  /**
   * Convert the pdf 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

1. Check pdf.type === 'base64' before calling asBase64()
2. Download the PDF from its URL and base64-encode it when bytes are needed
3. Use Pdf.fromBase64(...) at construction if downstream consumers require base64

Example fix

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

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

const isBase64Pdf = (p) => p.type === 'base64';

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

When it happens

Trigger: Calling pdf.asBase64() on a Pdf whose type is 'url' (created via fromUrl), i.e. this.type !== 'base64'.

Common situations: Code that needs document bytes (uploading elsewhere, writing to disk, inlining into requests) receiving URL-referenced PDFs from model responses or 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

• BAML internal error (AWSBedrock): Pdf file should have been
• Pdf is not a URL
• BAML internal error (AWSBedrock): file should have been reso
• BAML internal error (AWSBedrock): video file should have bee
• BAML internal error (google-ai): file should have been resol

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