formidable

Postconditions — what we check

• parse · formidable-parse-error

  error
  Whenform parsing fails due to invalid data, size limits, or filesystem errors
  ThrowsFormidableError (extends Error) with .code (numeric) and .httpCode (HTTP status)
  Required handlingCaller MUST handle parsing errors with try-catch (promise-based) or callback error parameter. Without error handling, the server will crash when: maxFileSize exceeded (default 200MB), maxFields exceeded (default 1000), invalid multipart data is received, filesystem errors occur, or filter function validation fails. Promise-based (v3+): try { const [fields, files] = await form.parse(req); } catch (err) { res.status(err.httpCode || 400).send(err.message); } Callback: form.parse(req, (err, fields, files) => { if (err) { res.status(err.httpCode || 400).send(err.message); return; } })
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• parse · formidable-max-file-size-exceeded

  error
  Whenuploaded file exceeds options.maxFileSize (default: 200MB)
  ThrowsFormidableError with .code === 1016 (biggerThanMaxFileSize) and .httpCode === 413
  Required handlingCatch the error and return HTTP 413 Payload Too Large to the client. If not caught, the server process throws an unhandled rejection. Set maxFileSize explicitly in options to enforce your business limits rather than relying on the 200MB default. Example: if (err.code === errors.biggerThanMaxFileSize) { res.status(413).json({ error: 'File too large' }); }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-max-total-file-size-exceeded

  error
  Whenaggregate size of all uploaded files exceeds options.maxTotalFileSize (defaults to maxFileSize value)
  ThrowsFormidableError with .code === 1009 (biggerThanTotalMaxFileSize) and .httpCode === 413
  Required handlingCatch the error and return HTTP 413 to the client. This limit applies to the sum of all files in a multi-file upload. Without explicit maxTotalFileSize, it defaults to maxFileSize — meaning 100 small files each under the per-file limit can still exceed total size. Must be caught separately from the per-file limit (different error code).
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-max-fields-exceeded

  error
  Whennumber of submitted fields exceeds options.maxFields (default: 1000)
  ThrowsFormidableError with .code === 1007 (maxFieldsExceeded) and .httpCode === 413
  Required handlingCatch the error and return HTTP 413. This is a security control to prevent hash-collision DoS attacks via crafted field names. Without catching it, a malicious client can crash the server by submitting thousands of fields. Servers processing user-supplied forms must explicitly handle this to avoid being taken down by a single malicious request.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[2][1]
• parse · formidable-max-fields-size-exceeded

  error
  Whentotal size of all form fields exceeds options.maxFieldsSize (default: 20MB)
  ThrowsFormidableError with .code === 1006 (maxFieldsSizeExceeded) and .httpCode === 413
  Required handlingCatch the error and return HTTP 413. This limit applies to text fields only (not file uploads), protecting against memory exhaustion from very large text field payloads. Without catching it, a client sending a 20MB+ text field causes an unhandled rejection that crashes the server.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[2][3]
• parse · formidable-max-files-exceeded

  error
  Whennumber of uploaded files exceeds options.maxFiles (default: Infinity)
  ThrowsFormidableError with .code === 1015 (maxFilesExceeded) and .httpCode === 413
  Required handlingCatch the error and return HTTP 413. When maxFiles is not set (Infinity default), this error never fires — but setting a sane limit (e.g., 10) and not catching the resulting error will crash the server when exceeded. Always pair maxFiles configuration with proper error handling.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-missing-content-type

  error
  Whenrequest has no Content-Type header or an unsupported content type
  ThrowsFormidableError with .code === 1011 (missingContentType) and .httpCode === 400, or .code === 1003 (noParser) with .httpCode === 415
  Required handlingCatch the error and return the appropriate HTTP status to the client. This fires when form.parse() is called on a non-form request (e.g., a JSON request without the JSON plugin, or a raw request with no Content-Type). Common in API endpoints that receive form data from clients that forget the Content-Type header or send the wrong MIME type.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-malformed-multipart

  error
  Whenmultipart body is malformed, corrupted, or missing boundary
  ThrowsFormidableError with .code === 1012 (malformedMultipart) or 1013 (missingMultipartBoundary) and .httpCode === 400
  Required handlingCatch the error and return HTTP 400 Bad Request. This fires when the client sends a Content-Type: multipart/form-data header but the body is corrupted, truncated, or missing the required boundary parameter. Can occur from client bugs, network corruption, or crafted malicious requests. Without catching it, malformed uploads crash the server.
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[2][3]
• parse · formidable-request-aborted

  warning
  Whenclient disconnects mid-upload (request aborted)
  ThrowsFormidableError with .code === 1002 (aborted) and .httpCode === 400
  Required handlingCatch the error. Request aborts are normal client behavior (user cancels upload, network drops, browser navigates away) and should not crash the server. Without catching, every cancelled upload causes an unhandled rejection. In high-traffic applications with large file uploads, this is a common production failure mode.
  costmediumin proddelayed failureusers seedegraded performancevisibilitysilent
  Sources[2][3]
• parse · formidable-no-empty-files

  error
  Whenoptions.allowEmptyFiles is false (default) and client sends a 0-byte file
  ThrowsFormidableError with .code === 1010 (noEmptyFiles) and .httpCode === 400
  Required handlingCatch the error and return HTTP 400 to the client. With default settings (allowEmptyFiles: false), any 0-byte file upload triggers this error. This catches browsers that submit file inputs without selecting a file, resulting in an empty Blob upload. The default behavior enforces non-empty files — callers must handle the rejection or explicitly set allowEmptyFiles: true.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-cannot-create-dir

  error
  Whenoptions.createDirsFromUploads is true and the upload directory cannot be created
  ThrowsFormidableError with .code === 1018 (cannotCreateDir) and .httpCode === 409
  Required handlingCatch the error and return HTTP 409 or HTTP 500 to the client. This error only fires when createDirsFromUploads is explicitly enabled (for directory-structured uploads using webkitdirectory). Filesystem permission errors or path traversal prevention triggers this. Without catching, the server crashes on the first directory-based upload to an unwritable path.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][3]
• parse · formidable-plugin-failed

  error
  Whena registered plugin (built-in or via form.use(...)) throws or rejects during parse()
  ThrowsFormidableError with .code === 1017 (pluginFailed) and .httpCode === 500. The error has an .idx property indicating which plugin index failed, and the message includes the inner plugin error's message.
  Required handlingCatch the error from `await form.parse(req)`. On rejection: log the error including .idx so you know which plugin failed, return HTTP 500 to the client. Custom plugins that perform validation or transformation should throw FormidableError themselves with a more specific .httpCode (e.g. 400 for validation) so the calling code can return an appropriate status — the default 500 indicates an internal failure. Most applications will hit this only after wiring a custom `form.use(plugin)`; the built-in octetstream/querystring/multipart/json plugins do not throw under normal input. Inspect error.code === 1017 (or errors.pluginFailed) to distinguish plugin failures from parser/limit errors when handling.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][4]
• parse · formidable-smaller-than-min-file-size

  error
  Whenoptions.minFileSize is explicitly set above 1 and an uploaded file's size is below the threshold
  ThrowsFormidableError with .code === 1008 (smallerThanMinFileSize) and .httpCode === 400. Message: 'options.minFileSize (N bytes) inferior, received M bytes of file data'.
  Required handlingCatch the error and return HTTP 400 with a user-facing message explaining the minimum file size requirement. Without catching it, every upload below the threshold causes an unhandled rejection that crashes the server. Only fires when minFileSize is explicitly configured — at the default (1 byte) only truly empty files trigger noEmptyFiles instead. Common in image-upload flows that require a minimum resolution/quality, or audio upload flows that reject zero-content recordings.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[2][5]
• parse · formidable-unknown-transfer-encoding

  error
  Whenmultipart request part contains an unrecognized or unsupported Content-Transfer-Encoding header value
  ThrowsFormidableError with .code === 1014 (unknownTransferEncoding) and .httpCode === 501 (Not Implemented). Message: 'unknown transfer-encoding'.
  Required handlingCatch the error and return HTTP 501 (or HTTP 400 with a clearer client-facing explanation) — the upload contained encoding the parser cannot process. Without catching, the server crashes on malformed/exotic multipart parts. Most modern HTTP clients send only `binary`, `7bit`, or `8bit` and never trigger this; it surfaces against legacy clients, non-browser uploaders, or adversarial requests crafted to probe for parser handling. Treat it as a client error in normal flows — do not retry the request.
  costlowin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[2][6]
• parse · formidable-filename-not-string

  error
  Whena multipart part declares a Content-Disposition `filename` that is not a string (e.g. malformed/attacker-crafted header)
  ThrowsFormidableError with .code === 1005 (filenameNotString) and .httpCode === 500. Message: 'the part.originalFilename should be string when it exists'.
  Required handlingCatch the error and return HTTP 400 (treat as a malformed client request, NOT a server fault — override the 500 default with a 400 if surfacing to the client). Log the request for security review: this error is one of formidable's input-validation guardrails against header injection. Most legitimate clients never hit it. Without catching, the server crashes on the first crafted upload — a denial-of-service vector. Defenders should rate-limit endpoints that surface this error code repeatedly from the same client.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitysilent
  Sources[2][7]

Sources

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

1. [1]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/README.md
2. [2]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/FormidableError.js
3. [3]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/Formidable.js
4. [4]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/Formidable.js#L466-L481
5. [5]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/Formidable.js#L415-L422
6. [6]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/plugins/multipart.js#L154-L160
7. [7]github.com/node-formidable/formidablehttps://github.com/node-formidable/formidable/blob/master/src/Formidable.js#L310-L318