Cannot convert URL-backed generated file to Uint8Array. Down

Error message

Cannot convert URL-backed generated file to Uint8Array. Download the file from ${this.base64Data} instead.

What it means

Mastra's GeneratedFile lazily converts base64 data to a Uint8Array. Files produced by newer (AI SDK v7-style) models can be URL-backed: the URL string is stored in base64Data. Decoding a URL as base64 would silently produce garbage, so uint8Array fails loudly and tells you to download from the URL instead.

Source

Thrown at packages/core/src/stream/aisdk/v5/file.ts:53

    this.uint8ArrayData = isUint8Array ? data : undefined;
    this.mediaType = mediaType;
  }

  // lazy conversion with caching to avoid unnecessary conversion overhead:
  get base64() {
    if (this.base64Data == null) {
      this.base64Data = convertUint8ArrayToBase64(this.uint8ArrayData!);
    }
    return this.base64Data;
  }

  // lazy conversion with caching to avoid unnecessary conversion overhead:
  get uint8Array() {
    if (this.uint8ArrayData == null) {
      // URL-backed generated files (AI SDK v7 models) store the URL string in
      // place of base64. Fail loudly instead of decoding the URL as base64.
      if (isUrlString(this.base64Data!)) {
        throw new Error(
          `Cannot convert URL-backed generated file to Uint8Array. Download the file from ${this.base64Data} instead.`,
        );
      }
      this.uint8ArrayData = convertBase64ToUint8Array(this.base64Data!);
    }
    return this.uint8ArrayData;
  }
}

export class DefaultGeneratedFileWithType extends DefaultGeneratedFile {
  readonly type = 'file';

  constructor(options: { data: string | Uint8Array; mediaType: string }) {
    super(options);
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

Detect URL-backed files and fetch(url) to download the bytes yourself instead of reading uint8Array
Use the file's URL property directly (pass the URL to consumers, store it, or stream it)
Upgrade @mastra/core to a version whose helpers handle URL-backed files (e.g. a download helper)
Wrap access in a check: if the value looks like an https URL, fetch it; otherwise decode base64

Example fix

// before
const bytes = file.uint8Array;
fs.writeFileSync('out.mp4', bytes);
// after
if (/^https?:\/\//.test(file.base64Data ?? '')) {
  const res = await fetch(file.base64Data!);
  fs.writeFileSync('out.mp4', Buffer.from(await res.arrayBuffer()));
} else {
  fs.writeFileSync('out.mp4', file.uint8Array);
}

Defensive patterns

Strategy: validation

Validate before calling

function fileBytes(file: { base64Data?: string; uint8Array: Uint8Array }): Promise<Uint8Array> {
  const src = file.base64Data;
  if (src && /^https?:\/\//.test(src)) {
    return fetch(src).then(r => new Uint8Array(r.arrayBuffer()));
  }
  return Promise.resolve(file.uint8Array);
}

Type guard

function isUrlBackedFile(f: { base64Data?: string | null }): boolean {
  return typeof f.base64Data === 'string' && /^https?:\/\//.test(f.base64Data);
}

Try / catch

try {
  bytes = file.uint8Array;
} catch (e) {
  if (String(e).includes('URL-backed generated file')) {
    const res = await fetch(file.base64Data!);
    bytes = new Uint8Array(await res.arrayBuffer());
  } else throw e;
}

Prevention

Check base64Data for an http(s) URL before touching uint8Array
Use a shared accessor helper for generated files so URL handling lives in one place
Remember new models may return hosted URLs — don't assume inline base64
Handle fetch failures when downloading URL-backed files

When it happens

Trigger: Calling file.uint8Array (or APIs that transitively access it, like writing to disk) on a generated file whose source model returned a hosted URL rather than inline base64 data.

Common situations: Using a model that hosts generated files (e.g. video/image generation with signed URLs) and then treating the result like local base64 data; code written for older models that always returned base64.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/94e011b2dba21deb. Report an issue: GitHub.