mastra-ai/mastra · error · MastraError

MASTRA_AIV5_DATA_PART_INVALID

MASTRA_AIV5_DATA_PART_INVALID

Error message

Invalid AIV5 data part in getDataStringFromAIV5DataPart

What it means

MastraError thrown by getDataStringFromAIV5DataPart in the AIV5 adapter when a data part claims to be media (image/file) but contains no recognizable payload. The function expects part.image, part.data, or a string part.url; a part with none of these cannot be converted to a data URL/string. Categorized USER because the malformed part came from input messages.

Source

Thrown at packages/core/src/agent/message-list/adapters/AIV5Adapter.ts:803

    };
  }

  /**
   * Convert image or file to data URI or URL for V2 file part
   */
  private static getDataStringFromAIV5DataPart(part: AIV5Type.ImagePart | AIV5Type.FilePart): string {
    let mimeType: string;
    let data: AIV5.FilePart['data'] | AIV5.ImagePart['image'];
    if ('data' in part) {
      mimeType = part.mediaType || 'application/octet-stream';
      data = part.data;
    } else if ('image' in part) {
      mimeType = part.mediaType || 'image/jpeg';
      data = part.image;
    } else if ('url' in part && typeof (part as any).url === 'string') {
      return (part as any).url;
    } else {
      throw new MastraError({
        id: 'MASTRA_AIV5_DATA_PART_INVALID',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: 'Invalid AIV5 data part in getDataStringFromAIV5DataPart',
        details: {
          part,
        },
      });
    }

    if (data instanceof URL) {
      return data.toString();
    } else {
      if (data instanceof Buffer) {
        const base64 = data.toString('base64');
        return `data:${mimeType};base64,${base64}`;
      } else if (typeof data === 'string') {
        // OpenAI Files API file IDs (e.g. "file-abc123") must pass through as-is so

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure the data part carries one of: a string url, base64 data in part.data, bytes/buffer in part.image (for images), per AI SDK v5 FilePart/DataPart shape.
If you have a URL, pass it as { type: 'file', url: 'https://...' } with url as a string, not a URL instance.
For images use { type: 'image', image: <Uint8Array|base64 string|data URL>, mediaType: 'image/png' }.
Verify persisted messages still contain the data payload after serialization round-trips; log details.part from the error to see what arrived.

Example fix

// before
{ type: 'file', mediaType: 'application/pdf', filename: 'doc.pdf' }

// after
{ type: 'file', mediaType: 'application/pdf', data: base64EncodedPdf }

Defensive patterns

Strategy: type-guard

Validate before calling

function assertExtractableMediaPart(part: any): void {
  const hasPayload = typeof part?.url === 'string' || part?.data != null || part?.image != null;
  if (!hasPayload) throw new Error(`Media part missing url/data/image: ${JSON.stringify(part).slice(0, 200)}`);
}

Type guard

function hasMediaPayload(p: any): p is { url: string } | { data: string | Uint8Array } | { image: string | Uint8Array } {
  return !!p && (typeof p.url === 'string' || p.data != null || p.image != null);
}

Try / catch

try {
  const dataString = getDataStringFromAIV5DataPart(part);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_AIV5_DATA_PART_INVALID') {
    logger.warn('Skipping media part without payload', e.details.part);
    return null;
  }
  throw e;
}

Prevention

Always attach the binary payload (base64/Uint8Array) or a string url when constructing file/image data parts.
Convert URL objects to strings before embedding in messages.
Verify media survives your storage round-trip — binary fields are often dropped by JSON serialization.
Follow AI SDK v5 FilePart shape exactly when upgrading from v4 message formats.

When it happens

Trigger: Adding an AIV5 message whose file part has neither data/image bytes nor a string url (e.g. { type: 'file', mediaType: 'application/pdf' } with no data), or an image part where image is undefined/null or an unsupported object type, reached via imageData/fileData converters.

Common situations: Serializing messages where binary data was dropped (e.g. stored without the base64 payload); passing a URL object instead of a URL string; sending a file part with only a filename; upgrading from v4 messages whose media shape differs from v5 data parts.

Related errors

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