mastra-ai/mastra · error

Media type is missing for file part

Error message

Media type is missing for file part

What it means

Unlike images (which can fall back to 'image/*'), file parts must have a concrete mediaType for the provider request. After conversion/download attempts, if convertImageFilePart still has no mediaType for a 'file' part, it throws 'Media type is missing for file part'.

Source

Thrown at packages/core/src/agent/message-list/prompt/convert-file.ts:60

      // to deal with incorrect media type inputs.
      // When detection fails, use provided media type.
      if (data instanceof Uint8Array || typeof data === 'string') {
        mediaType = detectMediaType({ data, signatures: imageMediaTypeSignatures }) ?? mediaType;
      }

      return {
        type: 'file',
        mediaType: mediaType ?? 'image/*', // any image
        filename: undefined,
        data,
        providerOptions: part.providerOptions,
      };
    }

    case 'file': {
      // We must have a mediaType for files, if not, throw an error.
      if (mediaType == null) {
        throw new Error(`Media type is missing for file part`);
      }

      return {
        type: 'file',
        mediaType,
        filename: part.filename,
        data,
        providerOptions: part.providerOptions,
      };
    }
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set mediaType explicitly on the FilePart (or contentType on the originating attachment).
2. Serve the asset with a proper Content-Type header so download-assets can capture it.
3. For URLs, ensure the asset is included in downloadedAssets (run downloadAssets so the header-derived media type is available).
4. If the data is an image, use an image part or set 'image/png'-style mediaType instead of relying on fallback detection.

Example fix

// before
{ type: 'file', data: 'https://cdn.example.com/report' }
// after
{ type: 'file', data: 'https://cdn.example.com/report', mediaType: 'application/pdf' }

function assertFilePartHasMediaType(part: { type: 'file'; mediaType?: string; data: unknown }) {
  if (part.type === 'file' && !part.mediaType) {
    throw new Error('FilePart requires mediaType before prompt conversion');
  }
}

function isTypedFilePart(p: { type: string; mediaType?: string }): p is { type: 'file'; mediaType: string; data: unknown } {
  return p.type === 'file' && typeof p.mediaType === 'string' && p.mediaType.includes('/');
}

try {
  converted = convertImageFilePart(part, downloadedAssets);
} catch (e) {
  if (e instanceof Error && e.message.includes('Media type is missing')) {
    converted = convertImageFilePart({ ...part, mediaType: 'application/octet-stream' }, downloadedAssets);
  } else throw e;
}

When it happens

Trigger: A FilePart whose data yields no detectable media type (URL not in downloadedAssets or response lacked content-type) and whose part.mediaType / attachment.contentType was never set — e.g. { type: 'file', data: url } with no mimeType anywhere in the chain.

Common situations: Downloading assets from servers that omit the Content-Type header; building FileParts manually from raw base64 without mimeType; gs:// or s3:// attachments where contentType was inferred as image only for some files.

Related errors

• If the attachment is not an image, it must specify a content
• If the attachment is not an image or text, it must specify a
• Unsupported part type: ${type}
• Invalid \`mediaTypes\` pattern: ${JSON.stringify(pattern)}.
• [Schema Builder] Failed to convert schema parameters to Zod.

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