What causes "No files were uploaded." in payloadcms/payload?

Attach a file to the request (`multipart/form-data` with the file part) when creating on an upload collection.

payloadcms/payload · error · MissingFile

No files were uploaded.

Error message

No files were uploaded.

What it means

`generateFileData` resolves the file to process from `req.file`, duplication, or re-upload. If after all of those checks `file` is still falsy and the caller passed `throwOnMissingFile: true`, Payload throws `MissingFile` (HTTP 400, message `No files were uploaded.`). When `throwOnMissingFile` is false, the function instead returns the incoming data with an empty `files` array (a no-op update).

Source

Thrown at packages/payload/src/uploads/generateFileData.ts:156

        file = await getExternalFile({
          data: incomingFileData as unknown as FileData,
          req,
          uploadConfig: collectionConfig.upload,
        })
        overwriteExistingFiles = true
      }
    } catch (err: unknown) {
      throw new FileRetrievalError(req.t, err instanceof Error ? err.message : undefined)
    }
  }

  if (isDuplicating) {
    overwriteExistingFiles = false
  }

  if (!file) {
    if (throwOnMissingFile) {
      throw new MissingFile(req.t)
    }

    return {
      data: incomingFileData!,
      files: [],
    }
  }

  await checkFileRestrictions({
    collection: collectionConfig,
    file,
    req,
  })

  if (!disableLocalStorage) {
    await fs.mkdir(staticPath!, { recursive: true })
  }

View on GitHub (pinned to 00c58b35c0)

Solutions

Attach a file to the request (`multipart/form-data` with the file part) when creating on an upload collection.
If the collection should allow file-less creates, set `upload.filesRequiredOnCreate: false`.
Ensure your HTTP layer (formidable/busboy/Next.js route) actually populates `req.file` from the multipart body.
For updates that legitimately change only metadata, confirm the operation is `update` and not flagged to require a file.

Example fix

// before — creating an upload doc without a file
await payload.create({
  collection: 'media',
  data: { alt: 'no file attached' },
})

// after — either attach a file or relax the requirement
const form = new FormData()
form.append('file', fileBlob, 'photo.png')
form.append('alt', 'caption')
await fetch(`${url}/api/media`, { method: 'POST', body: form })

// OR disable the requirement
const Media = { slug: 'media', upload: { filesRequiredOnCreate: false } }

Defensive patterns

Strategy: validation

Validate before calling

function hasFile(file: unknown): boolean {
  return !!file && (typeof (file as any).data !== 'undefined' || typeof (file as any).tempFilePath === 'string')
}

if (!hasFile(req.file)) {
  if (collection.upload?.filesRequiredOnCreate === false) {
    // proceed without a file
  } else {
    throw new Error('A file is required to create on this upload collection')
  }
}

Type guard

function hasAttachedFile(file: unknown): file is { data: Buffer; name: string; mimetype: string; size: number } {
  return !!file && typeof file === 'object' &&
    typeof (file as any).name === 'string' &&
    (Buffer.isBuffer((file as any).data) || typeof (file as any).tempFilePath === 'string')
}

Try / catch

try {
  await payload.create({ collection: 'media', data, file })
} catch (err) {
  if (err instanceof Error && /no files were uploaded/i.test(err.message)) {
    if (allowFileless) {
      // set upload.filesRequiredOnCreate: false and retry
    } else {
      // prompt the user to attach a file
    }
  } else throw err
}

Prevention

Attach a real file part on creates against upload collections.
Set `upload.filesRequiredOnCreate: false` if file-less creates are valid.
Verify your multipart handler populates `req.file`.

When it happens

Trigger: A create/update operation on an upload collection where `req.file` is undefined, the operation is not a duplication, `shouldReupload` is false (no upload edits), and the collection/operation was configured with `throwOnMissingFile: true`. Payload's collection create flow sets this true when `filesRequiredOnCreate` is in effect; updates typically pass it based on whether a file is required.

Common situations: Creating a document on an upload collection without attaching a file (default `filesRequiredOnCreate` is true). A multipart parser misconfigured so `req.file` is never populated. The client sent JSON only, omitting the file part. An update was expected to attach a new file but the form had no file field.

Related errors

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