payloadcms/payload · error · FileRetrievalError

Unable to determine mimetype for file: ${doc.filename}

Error message

Unable to determine mimetype for file: ${doc.filename}

What it means

In the synchronous import path (getImportCollection with disableJobsQueue), the hook prefers req.file.data. It derives the mimetype from req.file.mimetype falling back to doc.mimeType; if both are absent it throws FileRetrievalError before parsing.

Source

Thrown at packages/plugin-import-export/src/import/getImportCollection.ts:111

    }

    if (!disableJobsQueue) {
      return doc
    }

    try {
      // Get file data from the uploaded document
      // First try req.file which is available during the same request (especially important for cloud storage)
      // Fall back to getFileFromDoc for cases where req.file isn't available
      let fileData: Buffer
      let fileMimetype: string

      if (req.file?.data) {
        fileData = req.file.data
        fileMimetype = req.file.mimetype || doc.mimeType

        if (!fileMimetype) {
          throw new FileRetrievalError(
            req.t,
            `Unable to determine mimetype for file: ${doc.filename}`,
          )
        }
      } else {
        const fileFromDoc = await getFileFromDoc({
          collectionConfig,
          doc: {
            filename: doc.filename,
            mimeType: doc.mimeType,
            url: doc.url,
          },
          req,
        })
        fileData = fileFromDoc.data
        fileMimetype = fileFromDoc.mimetype
      }

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure the upload includes a mimetype so req.file.mimetype is set.
2. Persist doc.mimeType on the imports collection and backfill existing docs.
3. If using cloud storage, verify the doc has mimeType before the sync hook runs.

const fileMimetype = req.file?.mimetype || doc.mimeType
if (req.file?.data && !fileMimetype) {
  throw new Error('Upload has no mimetype and doc.mimeType is unset')
}

const uploadHasMimetype = (req: PayloadRequest, doc: { mimeType?: unknown }): boolean =>
  !!(req.file?.mimetype || doc.mimeType)

When it happens

Trigger: An upload arrives where req.file has data but no mimetype, and the persisted doc also lacks mimeType. Typical of direct API uploads that omit the multipart mimetype or a doc schema without a mimeType field.

Common situations: Custom API client posting a file without a Content-Type part; cloud-storage path where req.file isn't populated and doc.mimeType was never set.

Related errors

• Unable to determine mimetype for file: ${importDoc.filename}
• No file data provided for import
• Unable to determine mimetype for file: ${doc.filename}
• Unable to retrieve file: missing filename or url
• Collection with slug ${collectionSlug} not found

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/4f6e777f662493a4. Report an issue: GitHub.