Profiles·Public

busboy

semver>=1.0.0postconditions9functions1last verified2026-04-16coverage score90%

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]

Sources

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

Need a different package?

Request a profile