{"record":{"id":"05054c9607814531","repo":"payloadcms/payload","slug":"unable-to-retrieve-file-missing-filename-or-url","errorCode":null,"errorMessage":"Unable to retrieve file: missing filename or url","messagePattern":"Unable to retrieve file: missing filename or url","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/plugin-import-export/src/utilities/getFileFromDoc.ts","lineNumber":92,"sourceCode":"    const file = await getExternalFile({\n      data: { filename: doc.filename, url: fileUrl } as FileData,\n      req,\n      uploadConfig,\n    })\n\n    const mimetype = file.mimetype || doc.mimeType\n\n    if (!mimetype) {\n      throw new FileRetrievalError(req.t, `Unable to determine mimetype for file: ${doc.filename}`)\n    }\n\n    return {\n      data: file.data,\n      mimetype,\n    }\n  }\n\n  throw new Error('Unable to retrieve file: missing filename or url')\n}\n","sourceCodeStart":74,"sourceCodeEnd":94,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/plugin-import-export/src/utilities/getFileFromDoc.ts#L74-L94","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure uploads persist both filename and url on the doc.","If storing external URLs only, also populate filename so the cloud branch can run.","Validate the doc shape before calling getFileFromDoc."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"function assertFileRef(doc: { filename?: string; url?: string }) {\n  const hasLocal = !!doc.filename\n  const hasCloud = !!doc.filename && !!doc.url\n  if (!hasLocal && !hasCloud) {\n    throw new Error('doc must have filename (local) or filename+url (cloud)')\n  }\n}","typeGuard":"const isRetrievableDoc = (d: { filename?: unknown; url?: unknown }): boolean =>\n  typeof d.filename === 'string' && (d.filename.length > 0)","tryCatchPattern":null,"preventionTips":["Persist both filename and url on upload docs.","For external-URL storage, still set filename so the cloud branch can run.","Validate the doc shape in an afterChange hook before imports can reference it."],"tags":["storage","file-upload","import","plugin-import-export"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}