Postconditions: what we check

• Busboy · busboy-001

  error
  Whenparsing fails due to limits or malformed data
  ThrowsError emitted via 'error' event
  Required handlingCaller MUST attach error event listener to Busboy instance
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Busboy · busboy-002

  error
  Whenconstructor called with invalid or missing Content-Type header
  ThrowsError (synchronous throw, not an event)
  Required handlingCaller MUST wrap busboy() constructor call in try/catch. These are synchronous throws — an error event listener is NOT sufficient to catch them. Any request without a valid Content-Type (e.g. GET requests misrouted to a POST handler) will crash the process if not caught.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][3]
• Busboy · busboy-003

  warning
  Whenform data exceeds configured parts, files, or fields limits
  ThrowsNo error — emits 'partsLimit', 'filesLimit', or 'fieldsLimit' event then silently stops
  Required handlingCaller SHOULD attach listeners for 'partsLimit', 'filesLimit', and 'fieldsLimit' events to detect when limits are reached. Without these listeners, the upload appears to succeed but data is silently truncated — fields and files beyond the limit are never delivered to the 'field' or 'file' handlers. This is especially dangerous when limits are set intentionally as a security measure: an attacker can send more fields/files than the limit and the overflow is silently dropped with no error to the caller.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[4][5]
• Busboy · busboy-004

  error
  Whenuploaded file exceeds configured limits.fileSize
  ThrowsNo error — emits 'limit' event on the file stream and sets file.truncated = true
  Required handlingCaller MUST check file.truncated after the file stream ends (in the 'close' or 'end' event handler). Without this check, the upload handler saves a partial file as if it were complete, silently corrupting stored data. The caller should also attach a 'limit' event listener on the file stream to detect the truncation in real time and abort the upload (e.g. delete the partial file, return 413).
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[4][6]
• Busboy · busboy-005

  error
  Whenfile event listener registered but file stream not consumed
  ThrowsNo error — causes stream deadlock; busboy 'close'/'finish' event never fires
  Required handlingWhen registering a 'file' event listener on a Busboy instance, the caller MUST consume every file stream. Use stream.resume() to discard contents if the file is not needed. Failing to consume the stream blocks all further parsing — the busboy 'close' event never fires, the request hangs indefinitely, and subsequent requests are blocked if using connection pooling. This is a common source of upload handler timeouts in production.
  costmediumin proddelayed failureusers seedegraded performancevisibilitysilent
  Sources[7][8]
• Busboy · busboy-006

  warning
  Whenfield value exceeds limits.fieldSize (default 1MB) without checking info.valueTruncated
  ThrowsNo error — field event fires with truncated value and info.valueTruncated = true
  Required handlingWhen handling the 'field' event, the caller SHOULD check info.valueTruncated to detect silently truncated field values. The default limit is 1MB (1048576 bytes) which can be easily exceeded by textarea inputs, JSON blobs, or base64-encoded data submitted as form fields. Busboy does not emit any error or event when fieldSize is exceeded — the truncated value is delivered to the 'field' callback as if it were complete. Applications that store field values without checking info.valueTruncated will silently persist corrupt, incomplete data to their database.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[7][4]
• Busboy · busboy-007

  error
  Whenclient disconnects or aborts upload before multipart data is fully received
  ThrowsError emitted via 'error' event: 'Unexpected end of form' or 'Unexpected end of file'
  Required handlingCaller MUST attach an 'error' event listener to the Busboy instance (covered by busboy-001) AND should handle the specific 'Unexpected end of form' and 'Unexpected end of file' error messages gracefully. These errors occur when: (1) the client drops the connection mid-upload (mobile network switch, browser tab closed), (2) a proxy or load balancer times out the request body, (3) the multipart data is malformed and missing the final boundary terminator. Without an error listener, Node.js throws an unhandled error event crashing the server. With a listener, the handler should clean up any partially-written files and return 400/499.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][9][10]
• Busboy · busboy-008

  error
  WhenContent-Type is multipart/form-data but boundary parameter is missing
  ThrowsError (synchronous throw): 'Multipart: Boundary not found'
  Required handlingCaller MUST wrap busboy() constructor in try/catch (see busboy-002) to also catch this specific throw. This error occurs when a client sends 'Content-Type: multipart/form-data' without the required ';boundary=<token>' parameter. This can happen with: (1) programmatic HTTP clients that set the Content-Type manually without generating a boundary, (2) curl requests where --form sets the boundary but manual -H 'Content-Type: ...' overrides it, (3) proxies or middleware that strip or rewrite Content-Type headers. The try/catch from busboy-002 is sufficient to catch this — no separate handler needed. Returning HTTP 400 is the correct response.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][3]
• Busboy · busboy-009

  info
  Whenform field name exceeds limits.fieldNameSize (default 100 bytes) without checking info.nameTruncated
  ThrowsNo error — field event fires with truncated name and info.nameTruncated = true
  Required handlingWhen handling the 'field' event, the caller SHOULD check info.nameTruncated to detect truncated field names. The default limit is 100 bytes. While most static form field names are short and will never hit this limit, dynamic field names from JSON→FormData conversions or array-style field names (e.g. 'items[0][metadata][description]') can exceed 100 bytes. A truncated field name will silently mismatch the application's expected field name, causing the data to be silently ignored or stored under an unexpected key.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[7][11]
• Busboy · busboy-010

  error
  Whenindividual multipart part header is malformed mid-stream after parsing has begun
  ThrowsError emitted via 'error' event on busboy instance: 'Malformed part header'
  Required handlingCaller MUST attach an 'error' event listener on the Busboy instance (already required by busboy-001 and busboy-007). This specific error fires when one part inside a multipart body has unparseable headers — the overall content type passed the constructor checks (busboy-002 / busboy-008), so try/catch alone is insufficient. Common triggers: hand-crafted multipart bodies from test fixtures or buggy HTTP clients that omit Content-Disposition on a part; intermediate proxies that rewrite headers in-place and break the boundary framing; malformed encoding parameters in the per-part headers. The handler should treat this as a 400 Bad Request, clean up any file streams already opened on previous successful parts, and abort the request. Distinguishing from 'Unexpected end of form' (busboy-007) matters because Malformed part header is a CLIENT error (deterministic, retrying won't help) while 'Unexpected end of form' is often a TRANSIENT network error (retry may succeed). Treating both as 400 conflates them — splitting them lets metrics separate client bugs from network instability.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][9]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

// ❌ BAD - can crash server
const busboy = new Busboy({ headers: req.headers });

// ✅ GOOD - wrapped in try-catch
try {
  const busboy = new Busboy({ headers: req.headers });
} catch (error) {
  // Handle invalid headers
}

// ❌ BAD - unhandled error event can crash server
const busboy = new Busboy({ headers: req.headers });
req.pipe(busboy);

// ✅ GOOD - error event listener added
const busboy = new Busboy({ headers: req.headers });
busboy.on('error', (err) => {
  console.error('Parse error:', err);
});
req.pipe(busboy);