payloadcms/payload · error · Error

File not found at path: ${filePath}

Error message

File not found at path: ${filePath}

What it means

getFileFromDoc reads local files from disk via getFileByPath(`${staticDir}/${filename}`). If that returns null (file absent on disk) it throws a plain Error with the resolved path. staticDir defaults to the collection slug when uploadConfig.staticDir is unset.

Source

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

 * - For cloud storage: fetches via Payload's file endpoint, which triggers
 *   the storage adapter's staticHandler to serve the file
 */
export const getFileFromDoc = async ({ collectionConfig, doc, req }: Args): Promise<Result> => {
  const uploadConfig: UploadConfig =
    typeof collectionConfig.upload === 'object' ? collectionConfig.upload : {}
  const disableLocalStorage = uploadConfig.disableLocalStorage ?? false
  const staticDir = uploadConfig.staticDir || collectionConfig.slug

  const serverURL = req.payload.config.serverURL
  const isLocalFile = (serverURL && doc.url?.startsWith(serverURL)) || doc.url?.startsWith('/')

  if (!disableLocalStorage && isLocalFile && doc.filename) {
    // Local storage enabled - read directly from disk (efficient, no HTTP roundtrip)
    const filePath = `${staticDir}/${doc.filename}`
    const file = await getFileByPath(filePath)

    if (!file) {
      throw new Error(`File not found at path: ${filePath}`)
    }

    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,
    }
  }

  if (doc.filename && doc.url) {
    // Cloud storage or external - fetch via Payload's file endpoint
    // getExternalFile constructs full URL, includes cookies for auth, and
    // the request goes through Payload's handler chain (including storage adapter)

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Confirm the file exists at the resolved `${staticDir}/${filename}` path on the running host.
2. Verify uploadConfig.staticDir matches where files are actually written.
3. If files moved to cloud storage, update doc.url so isLocalFile is false and the cloud branch is used.

import { existsSync } from 'fs'
const staticDir = uploadConfig.staticDir || collectionConfig.slug
const filePath = `${staticDir}/${doc.filename}`
if (!existsSync(filePath)) {
  throw new Error(`Local file missing on disk: ${filePath}`)
}

When it happens

Trigger: The file referenced by the doc is not present on disk: deleted, moved during migration, never written, or staticDir points to the wrong directory. The doc.url must look local (starts with serverURL or '/') to reach this branch.

Common situations: Volume not mounted in a new environment; files migrated to cloud storage but DB rows still reference local URLs; staticDir changed (e.g. collection renamed) leaving orphan paths.

Related errors

• Unable to retrieve file: missing filename or url
• No file data provided for import
• Collection with slug ${collectionSlug} not found
• Import file contains ${documents.length} documents but limit
• Import document not found: ${importId}

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