multer

Postconditions — what we check

• single · single-throws-multer-error

  error
  Whenfile upload fails due to size limit, file type, or disk error
  ThrowsMulterError
  Required handlingCaller MUST add error handling middleware after multer to catch MulterError. Check error.code for specific failure reason (LIMIT_FILE_SIZE, LIMIT_UNEXPECTED_FILE, etc.)
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• array · array-throws-multer-error

  error
  Whenone or more file uploads fail
  ThrowsMulterError
  Required handlingCaller MUST add error handling middleware after multer to catch MulterError. Multiple file uploads can fail individually or collectively.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• fields · fields-throws-multer-error-unexpected-file

  error
  WhenA file is received for a field not listed in the fields array, or the number of files for a given field exceeds its maxCount. Throws MulterError with code LIMIT_UNEXPECTED_FILE.
  ThrowsMulterError (code: LIMIT_UNEXPECTED_FILE)
  Required handlingCaller MUST add error handling middleware after the multer middleware to catch MulterError. Check error.code === 'LIMIT_UNEXPECTED_FILE' and error.field to identify which field caused the rejection. Without error middleware, the error is swallowed by Express's default handler and returns a generic 500.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][3]
• fields · fields-throws-multer-error-size-or-count

  error
  WhenAny file in any field exceeds the configured fileSize limit, or the total number of files across all fields exceeds the configured limits.files count. Throws MulterError with code LIMIT_FILE_SIZE or LIMIT_FILE_COUNT.
  ThrowsMulterError (code: LIMIT_FILE_SIZE | LIMIT_FILE_COUNT)
  Required handlingCaller MUST add error handling middleware and check error.code to differentiate between file size (LIMIT_FILE_SIZE) and count (LIMIT_FILE_COUNT) failures. Already-uploaded files are cleaned up by multer via storage._removeFile before calling next(err).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][3]
• any · any-unrestricted-upload-no-filter

  error
  WhenNo fileFilter is configured on the multer instance. Multer's any() method uses allowAll as the default fileFilter, accepting every file regardless of type or content. Malicious users can upload executables, scripts, or oversized files.
  ThrowsNo throw — dangerous silent success
  Required handlingCaller MUST configure fileFilter to validate file types and MUST configure limits.fileSize to prevent DoS. Without these, any() is a wide-open file upload endpoint. The official docs explicitly warn against using any() as global middleware.
  costhighin prodsilent failureusers seesecurity breachvisibilitysilent
  Sources[5][6]
• any · any-throws-multer-error-size

  error
  WhenA file exceeds the configured fileSize limit. MulterError with code LIMIT_FILE_SIZE is passed to next(err). Without error handling middleware, this returns a 500 error.
  ThrowsMulterError (code: LIMIT_FILE_SIZE)
  Required handlingCaller MUST add error handling middleware to catch MulterError from any() just as with single() and array(). The error includes the fieldname of the file that exceeded limits.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• none · none-throws-multer-error-on-file-upload

  error
  WhenA client sends a multipart request that includes any file field when none() is used. Multer immediately throws MulterError with code LIMIT_UNEXPECTED_FILE. This is by design — none() is a strict text-only enforcer.
  ThrowsMulterError (code: LIMIT_UNEXPECTED_FILE)
  Required handlingCaller MUST add error handling middleware to catch MulterError. Without it, a client that accidentally (or maliciously) includes a file will receive an unhandled Express 500 error instead of a clean 400 rejection. Recommended pattern: check err.code === 'LIMIT_UNEXPECTED_FILE' and return 400 with a descriptive message.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][6]
• diskStorage · disk-storage-destination-permission-error

  error
  WhenThe destination path string is passed to fs.mkdirSync() during DiskStorage construction. If the directory cannot be created due to permission errors (EACCES) or invalid path (ENOENT), the error is thrown synchronously at multer initialization — before any request is received.
  ThrowsError (code: EACCES | ENOENT | EPERM) — synchronous throw from fs.mkdirSync
  Required handlingWrap multer.diskStorage({ destination: '/path' }) in a try-catch at server startup, or use a function-form destination callback with proper error handling. Using function-form destination: if the callback passes an error as the first argument, it propagates to next(err) in the request middleware — catch it with error middleware.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8][9]
• diskStorage · disk-storage-write-error

  error
  WhenThe write stream created by fs.createWriteStream() emits an error during file upload (e.g., disk full, ENOSPC, EACCES on the file path, or the destination function returns an invalid path). The error propagates via storage._handleFile callback to multer's abortWithError(), which calls next(err).
  ThrowsError (code: ENOSPC | EACCES | ENOENT) — emitted by write stream
  Required handlingCaller MUST add error handling middleware to catch filesystem errors from diskStorage. Check error.code to distinguish disk full (ENOSPC) from permission errors (EACCES). Consider monitoring disk space and implementing alerts before ENOSPC occurs in production. Multer does attempt to clean up already-uploaded files via storage._removeFile on error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8][10]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/expressjs/multerhttps://github.com/expressjs/multer#error-handling
2. [2]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/README.md#fieldsfields
3. [3]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/lib/make-middleware.js
4. [4]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/README.md#limits
5. [5]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/README.md#anyoptions
6. [6]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/index.js
7. [7]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/README.md#noneoptions
8. [8]github.com/expressjs/multerhttps://github.com/expressjs/multer/blob/master/storage/disk.js
9. [9]nodejs.org/api/fs.htmlhttps://nodejs.org/api/fs.html#fsmkdirsyncpath-options
10. [10]nodejs.org/api/fs.htmlhttps://nodejs.org/api/fs.html#class-fswritestream