payloadcms/payload · error · Error

Unable to retrieve file: missing filename or url

Error message

Unable to retrieve file: missing filename or url

What it means

getFileFromDoc's terminal fallthrough. The local branch requires doc.filename (and a local-looking url); the cloud branch requires both doc.filename and doc.url. If neither branch matches (no usable filename/url combination), it throws a plain Error. This indicates an incomplete or corrupted doc record.

Source

Thrown at packages/plugin-import-export/src/utilities/getFileFromDoc.ts:92

    const file = await getExternalFile({
      data: { filename: doc.filename, url: fileUrl } as FileData,
      req,
      uploadConfig,
    })

    const mimetype = file.mimetype || doc.mimeType

    if (!mimetype) {
      throw new FileRetrievalError(req.t, `Unable to determine mimetype for file: ${doc.filename}`)
    }

    return {
      data: file.data,
      mimetype,
    }
  }

  throw new Error('Unable to retrieve file: missing filename or url')
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure uploads persist both filename and url on the doc.
2. If storing external URLs only, also populate filename so the cloud branch can run.
3. Validate the doc shape before calling getFileFromDoc.

function assertFileRef(doc: { filename?: string; url?: string }) {
  const hasLocal = !!doc.filename
  const hasCloud = !!doc.filename && !!doc.url
  if (!hasLocal && !hasCloud) {
    throw new Error('doc must have filename (local) or filename+url (cloud)')
  }
}

const isRetrievableDoc = (d: { filename?: unknown; url?: unknown }): boolean =>
  typeof d.filename === 'string' && (d.filename.length > 0)

When it happens

Trigger: doc has neither filename nor url; doc has a url but no filename (cloud branch needs both); doc.url doesn't look local so isLocalFile is false AND filename is missing.

Common situations: External URL stored in url but filename never set; doc created by a custom flow that bypassed normal upload field population; partial DB record after a failed upload.

Related errors

• No file data provided for import
• Unable to determine mimetype for file: ${importDoc.filename}
• Unable to determine mimetype for file: ${doc.filename}
• File not found at path: ${filePath}
• Unable to determine mimetype for file: ${doc.filename}

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