{"record":{"id":"882344f24ac77809","repo":"payloadcms/payload","slug":"there-was-a-problem-while-uploading-the-file-882344","errorCode":null,"errorMessage":"There was a problem while uploading the file.","messagePattern":"There was a problem while uploading the file\\.","errorType":"exception","errorClass":"FileUploadError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/uploads/uploadFiles.ts","lineNumber":21,"sourceCode":"import type { FileToSave } from './types.js'\n\nimport { FileUploadError } from '../errors/index.js'\nimport { saveBufferToFile } from './saveBufferToFile.js'\n\nexport const uploadFiles = async (\n  payload: Payload,\n  files: FileToSave[],\n  req: PayloadRequest,\n): Promise<void> => {\n  try {\n    await Promise.all(\n      files.map(async ({ buffer, path }) => {\n        await saveBufferToFile(buffer, path)\n      }),\n    )\n  } catch (err) {\n    payload.logger.error(err)\n    throw new FileUploadError(req.t)\n  }\n}\n","sourceCodeStart":3,"sourceCodeEnd":24,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/uploads/uploadFiles.ts#L3-L24","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check server disk space (`df -h`) and free space if full.","Verify the destination directory exists and the Node process has write permissions.","Check `upload.staticDir` configuration -- ensure it resolves to a real, writable path.","Reduce concurrent upload volume or raise the `ulimit -n` file-descriptor cap if EMFILE.","Inspect `payload.logger` output for the original OS error code (ENOSPC, EACCES, etc.) and address that specifically."],"exampleFix":"// before -- staticDir does not exist or is not writable\nupload: { staticDir: '/var/uploads/media' } // missing dir, wrong perms\n\n// after\nupload: { staticDir: path.resolve(process.cwd(), 'uploads/media') }\n// ensure: mkdir -p uploads/media && chown -R node:node uploads","handlingStrategy":"try-catch","validationCode":"// Before upload, verify disk space and directory writability\nconst fs = require('fs')\nconst dir = path.dirname(destPath)\nawait fs.promises.mkdir(dir, { recursive: true })\nawait fs.promises.access(dir, fs.constants.W_OK)","typeGuard":null,"tryCatchPattern":"try {\n  await uploadFiles(payload, files, req)\n} catch (e) {\n  if (e.name === 'FileUploadError') {\n    // check payload.logger for the underlying OS error code\n    // ENOSPC -> free space; EACCES -> fix permissions; ENOENT -> create dir\n  } else throw e\n}","preventionTips":["Pre-create upload directories and verify write permissions at startup.","Monitor disk space on upload servers.","Set ulimit -n appropriately for concurrent uploads.","Use the staticDir config to point to a persistent, writable volume."],"tags":["upload","filesystem","local-storage","io-error"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}