{"record":{"id":"94e011b2dba21deb","repo":"mastra-ai/mastra","slug":"cannot-convert-url-backed-generated-file-to-uint8a","errorCode":null,"errorMessage":"Cannot convert URL-backed generated file to Uint8Array. Download the file from ${this.base64Data} instead.","messagePattern":"Cannot convert URL-backed generated file to Uint8Array\\. Download the file from (.+?) instead\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/stream/aisdk/v5/file.ts","lineNumber":53,"sourceCode":"    this.uint8ArrayData = isUint8Array ? data : undefined;\n    this.mediaType = mediaType;\n  }\n\n  // lazy conversion with caching to avoid unnecessary conversion overhead:\n  get base64() {\n    if (this.base64Data == null) {\n      this.base64Data = convertUint8ArrayToBase64(this.uint8ArrayData!);\n    }\n    return this.base64Data;\n  }\n\n  // lazy conversion with caching to avoid unnecessary conversion overhead:\n  get uint8Array() {\n    if (this.uint8ArrayData == null) {\n      // URL-backed generated files (AI SDK v7 models) store the URL string in\n      // place of base64. Fail loudly instead of decoding the URL as base64.\n      if (isUrlString(this.base64Data!)) {\n        throw new Error(\n          `Cannot convert URL-backed generated file to Uint8Array. Download the file from ${this.base64Data} instead.`,\n        );\n      }\n      this.uint8ArrayData = convertBase64ToUint8Array(this.base64Data!);\n    }\n    return this.uint8ArrayData;\n  }\n}\n\nexport class DefaultGeneratedFileWithType extends DefaultGeneratedFile {\n  readonly type = 'file';\n\n  constructor(options: { data: string | Uint8Array; mediaType: string }) {\n    super(options);\n  }\n}\n","sourceCodeStart":35,"sourceCodeEnd":70,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/stream/aisdk/v5/file.ts#L35-L70","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst bytes = file.uint8Array;\nfs.writeFileSync('out.mp4', bytes);\n// after\nif (/^https?:\\/\\//.test(file.base64Data ?? '')) {\n  const res = await fetch(file.base64Data!);\n  fs.writeFileSync('out.mp4', Buffer.from(await res.arrayBuffer()));\n} else {\n  fs.writeFileSync('out.mp4', file.uint8Array);\n}","handlingStrategy":"validation","validationCode":"function fileBytes(file: { base64Data?: string; uint8Array: Uint8Array }): Promise<Uint8Array> {\n  const src = file.base64Data;\n  if (src && /^https?:\\/\\//.test(src)) {\n    return fetch(src).then(r => new Uint8Array(r.arrayBuffer()));\n  }\n  return Promise.resolve(file.uint8Array);\n}","typeGuard":"function isUrlBackedFile(f: { base64Data?: string | null }): boolean {\n  return typeof f.base64Data === 'string' && /^https?:\\/\\//.test(f.base64Data);\n}","tryCatchPattern":"try {\n  bytes = file.uint8Array;\n} catch (e) {\n  if (String(e).includes('URL-backed generated file')) {\n    const res = await fetch(file.base64Data!);\n    bytes = new Uint8Array(await res.arrayBuffer());\n  } else throw e;\n}","preventionTips":["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"],"tags":["files","generated-files","url","aisdk"],"backgroundTag":"url-backed-file-download-required","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}