payloadcms/payload · error · FileUploadError

There was a problem while uploading the file.

Error message

There was a problem while uploading the file.

What it means

A `FileUploadError` thrown by `uploadFiles` when `saveBufferToFile` fails for one or more files during a local-storage write. The underlying error is logged via `payload.logger.error` before re-throwing as a typed Payload error.

Source

Thrown at packages/payload/src/uploads/uploadFiles.ts:21

import type { FileToSave } from './types.js'

import { FileUploadError } from '../errors/index.js'
import { saveBufferToFile } from './saveBufferToFile.js'

export const uploadFiles = async (
  payload: Payload,
  files: FileToSave[],
  req: PayloadRequest,
): Promise<void> => {
  try {
    await Promise.all(
      files.map(async ({ buffer, path }) => {
        await saveBufferToFile(buffer, path)
      }),
    )
  } catch (err) {
    payload.logger.error(err)
    throw new FileUploadError(req.t)
  }
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Check server disk space (`df -h`) and free space if full.
2. Verify the destination directory exists and the Node process has write permissions.
3. Check `upload.staticDir` configuration -- ensure it resolves to a real, writable path.
4. Reduce concurrent upload volume or raise the `ulimit -n` file-descriptor cap if EMFILE.
5. Inspect `payload.logger` output for the original OS error code (ENOSPC, EACCES, etc.) and address that specifically.

Example fix

// before -- staticDir does not exist or is not writable
upload: { staticDir: '/var/uploads/media' } // missing dir, wrong perms

// after
upload: { staticDir: path.resolve(process.cwd(), 'uploads/media') }
// ensure: mkdir -p uploads/media && chown -R node:node uploads

// Before upload, verify disk space and directory writability
const fs = require('fs')
const dir = path.dirname(destPath)
await fs.promises.mkdir(dir, { recursive: true })
await fs.promises.access(dir, fs.constants.W_OK)

try {
  await uploadFiles(payload, files, req)
} catch (e) {
  if (e.name === 'FileUploadError') {
    // check payload.logger for the underlying OS error code
    // ENOSPC -> free space; EACCES -> fix permissions; ENOENT -> create dir
  } else throw e
}

When it happens

Trigger: Any filesystem error while writing the buffer to the configured `staticDir` / destination `path`: ENOSPC (disk full), EACCES (permission denied), ENOENT (parent directory missing), or EMFILE (too many open file handles).

Common situations: Disk full on the server; the upload `staticDir` does not exist and auto-create is off; the Node process lacks write permissions to the target directory; a path traversal or overly long filename causes an OS error; concurrent uploads exhaust file descriptors.

Related errors

• Could not read uploaded file for validation.
• There was an error deleting file.
• Invalid filename.
• storage contains an invalid entry: expected an object with a
• Field ${field.label} has reserved name '${fieldName}'.

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