body-parser

Postconditions — what we check

• json · malformed-json-throws

  error
  Whenrequest body is not valid JSON
  ThrowsSyntaxError with err.status === 400 and err.type === 'entity.parse.failed'
  Required handlingAn Express error-handling middleware with the signature (err, req, res, next) MUST be registered after all routes. Without it, malformed JSON payloads crash the entire application (DoS). The handler should check err instanceof SyntaxError && err.status === 400 && 'body' in err and return a 400 response.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1][2]
• json · payload-too-large

  error
  Whenrequest body exceeds the configured size limit (default 100kb)
  ThrowsError with err.type === 'entity.too.large' and err.status === 413
  Required handlingError-handling middleware MUST catch this error and return 413. The size limit SHOULD be configured explicitly based on application requirements. Values above 5MB increase memory pressure and DoS risk.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1][3]
• json · unsupported-charset

  error
  Whenrequest charset is not supported
  ThrowsError with err.type === 'charset.unsupported' and err.status === 415
  Required handlingError-handling middleware MUST catch this and return 415 Unsupported Media Type to the client.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• json · content-type-mismatch

  info
  Whenrequest Content-Type does not match the configured 'type' option
  ReturnsMiddleware calls next() without populating req.body
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• json · json-verify-failed

  error
  WhenThe optional 'verify' function throws an error when inspecting the raw request body buffer. This is used for HMAC signature verification (e.g. Stripe webhooks, GitHub webhooks).
  ThrowsError with err.status === 403 and err.type === 'entity.verify.failed' (or the custom type thrown by verify)
  Required handlingError-handling middleware MUST catch 403 errors from this middleware. When verify throws, the error propagates as a 403 Forbidden. Applications using webhook signature verification MUST handle this error gracefully — typically by returning 403 to the webhook sender. Without error handling, the server crashes or leaks unhandled promise rejections.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[4][1]
• json · json-encoding-unsupported

  error
  WhenRequest has a Content-Encoding header with an unsupported encoding (not 'gzip', 'deflate', or 'identity'), OR inflate option is set to false but request uses gzip or deflate encoding.
  ThrowsError with err.status === 415 and err.type === 'encoding.unsupported'
  Required handlingError-handling middleware MUST catch this and return 415. Common when APIs accept compressed requests (e.g. from CDNs or proxies) but inflate is disabled, or when clients send custom Content-Encoding headers. Without handling, the server returns an unhandled error to the client.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[5][4]
• json · json-size-invalid

  error
  WhenThe request body's actual byte length does not match the value in the Content-Length header. Typically caused by malformed proxied requests where Content-Length was calculated using character count rather than byte count (e.g. with multibyte Unicode).
  ThrowsError with err.status === 400 and err.type === 'request.size.invalid'
  Required handlingError-handling middleware MUST catch this and return 400. This error typically indicates a malformed upstream request or a proxy misconfiguration. Without handling, the middleware crashes the request with an unhandled error.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[6]
• json · json-stream-encoding-set

  error
  Whenreq.setEncoding() was called before this middleware ran. body-parser operates on raw bytes and is incompatible with stream encoding set at the Node.js level.
  ThrowsError with err.status === 500 and err.type === 'stream.encoding.set'
  Required handlingError-handling middleware MUST catch this. This is a developer configuration error — do NOT call req.setEncoding() when using body-parser. If this error appears in production, it indicates a middleware ordering bug that must be fixed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[7]
• json · json-stream-not-readable

  error
  WhenThe request body stream was already consumed before this middleware ran. This happens when two body-parser instances are registered for the same route, or when another middleware (e.g. busboy, multer) already read the request stream.
  ThrowsError with err.status === 500 and err.type === 'stream.not.readable'
  Required handlingError-handling middleware MUST catch this. This is a middleware ordering bug — each request body can only be read once. Ensure only one body-parsing middleware is registered per Content-Type. Use express-async-errors or a global error handler to surface this immediately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[8]
• urlencoded · payload-too-large

  error
  Whenrequest body exceeds the configured size limit
  ThrowsError with err.type === 'entity.too.large' and err.status === 413
  Required handlingError-handling middleware MUST catch this and return 413.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• urlencoded · too-many-parameters

  error
  Whennumber of URL-encoded parameters exceeds parameterLimit (default 1000)
  ThrowsError with err.type === 'parameters.too.many' and err.status === 413
  Required handlingError-handling middleware MUST catch this and return 413. The parameterLimit option SHOULD be reduced from the default of 1000 to the minimum required by the application to mitigate CVE-2025-13466 (DoS via parameter flooding).
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1][9]
• urlencoded · parse-failure

  error
  Whenbody cannot be parsed as URL-encoded data
  ThrowsError with err.type === 'entity.parse.failed' and err.status === 400
  Required handlingError-handling middleware MUST catch this and return 400.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• urlencoded · urlencoded-verify-failed

  error
  WhenThe optional 'verify' function throws when inspecting the raw request body buffer. Used for validating HMAC signatures or enforcing custom body policies.
  ThrowsError with err.status === 403 and err.type === 'entity.verify.failed' (or custom type)
  Required handlingError-handling middleware MUST catch this. When verify throws, a 403 Forbidden propagates through the middleware chain. Without error handling, the server crashes on the next unhandled error path.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[4][1]
• urlencoded · urlencoded-encoding-unsupported

  error
  WhenRequest has an unsupported Content-Encoding value, or inflate is false and gzip/deflate is used.
  ThrowsError with err.status === 415 and err.type === 'encoding.unsupported'
  Required handlingError-handling middleware MUST catch this and return 415.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[5][4]
• urlencoded · urlencoded-size-invalid

  error
  WhenActual body byte length does not match Content-Length header value.
  ThrowsError with err.status === 400 and err.type === 'request.size.invalid'
  Required handlingError-handling middleware MUST catch this and return 400.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[6]
• urlencoded · urlencoded-stream-encoding-set

  error
  Whenreq.setEncoding() was called before this middleware ran.
  ThrowsError with err.status === 500 and err.type === 'stream.encoding.set'
  Required handlingError-handling middleware MUST catch this. This is a developer configuration error — never call req.setEncoding() when using body-parser.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[7]
• urlencoded · urlencoded-stream-not-readable

  error
  WhenRequest stream was already consumed by another middleware before urlencoded parser ran.
  ThrowsError with err.status === 500 and err.type === 'stream.not.readable'
  Required handlingError-handling middleware MUST catch this. Typically caused by duplicate body-parsing middleware registrations. Only one body parser should be registered per Content-Type.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[8]
• urlencoded · urlencoded-qs-depth-exceeded

  error
  WhenThe extended option is true (qs parsing) and the nested parameter depth exceeds the configured depth option (default 32). For example: a[b][c][d]...[z]=1 with too many levels.
  ThrowsError with err.status === 400 (message contains "The input exceeded the depth")
  Required handlingError-handling middleware MUST catch this and return 400. Reduce the depth option to the minimum needed by your application (most apps need depth <= 5). Deep nesting can cause exponential memory allocation in older qs versions — set depth explicitly to a low value (e.g. { extended: true, depth: 5 }).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[10]
• raw · payload-too-large

  error
  Whenrequest body exceeds the configured size limit
  ThrowsError with err.type === 'entity.too.large' and err.status === 413
  Required handlingError-handling middleware MUST catch this and return 413.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• raw · content-type-mismatch

  info
  Whenrequest Content-Type does not match the configured 'type' option
  ReturnsMiddleware calls next() without populating req.body
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• raw · raw-verify-failed

  error
  WhenThe optional 'verify' function throws when inspecting the raw request body buffer. Common in webhook signature verification scenarios.
  ThrowsError with err.status === 403 and err.type === 'entity.verify.failed' (or custom type)
  Required handlingError-handling middleware MUST catch this. The raw parser is often used specifically for webhook HMAC verification (e.g. Stripe, GitHub). A failed signature check throws through the verify callback — without error handling this crashes the server.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[4][1]
• raw · raw-encoding-unsupported

  error
  WhenRequest has unsupported Content-Encoding, or inflate is false but gzip/deflate is sent.
  ThrowsError with err.status === 415 and err.type === 'encoding.unsupported'
  Required handlingError-handling middleware MUST catch this and return 415.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[5]
• raw · raw-size-invalid

  error
  WhenActual body byte length does not match Content-Length header.
  ThrowsError with err.status === 400 and err.type === 'request.size.invalid'
  Required handlingError-handling middleware MUST catch this and return 400.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[6]
• raw · raw-stream-encoding-set

  error
  Whenreq.setEncoding() was called before this middleware ran.
  ThrowsError with err.status === 500 and err.type === 'stream.encoding.set'
  Required handlingError-handling middleware MUST catch this. Developer error — never call req.setEncoding().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[7]
• raw · raw-stream-not-readable

  error
  WhenRequest stream was already consumed by another middleware.
  ThrowsError with err.status === 500 and err.type === 'stream.not.readable'
  Required handlingError-handling middleware MUST catch this. Only one body parser should run per request.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[8]
• text · payload-too-large

  error
  Whenrequest body exceeds the configured size limit
  ThrowsError with err.type === 'entity.too.large' and err.status === 413
  Required handlingError-handling middleware MUST catch this and return 413.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• text · unsupported-charset

  error
  Whenrequest charset is not supported
  ThrowsError with err.type === 'charset.unsupported' and err.status === 415
  Required handlingError-handling middleware MUST catch this and return 415.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[1]
• text · content-type-mismatch

  info
  Whenrequest Content-Type does not match the configured 'type' option
  ReturnsMiddleware calls next() without populating req.body
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• text · text-verify-failed

  error
  WhenThe optional 'verify' function throws when inspecting the raw request body buffer.
  ThrowsError with err.status === 403 and err.type === 'entity.verify.failed' (or custom type)
  Required handlingError-handling middleware MUST catch this. When verify throws, a 403 Forbidden propagates. Without error handling, the server crashes.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[4][1]
• text · text-encoding-unsupported

  error
  WhenRequest has unsupported Content-Encoding, or inflate is false but gzip/deflate is sent.
  ThrowsError with err.status === 415 and err.type === 'encoding.unsupported'
  Required handlingError-handling middleware MUST catch this and return 415.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[5]
• text · text-size-invalid

  error
  WhenActual body byte length does not match Content-Length header.
  ThrowsError with err.status === 400 and err.type === 'request.size.invalid'
  Required handlingError-handling middleware MUST catch this and return 400.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[6]
• text · text-stream-encoding-set

  error
  Whenreq.setEncoding() was called before this middleware ran.
  ThrowsError with err.status === 500 and err.type === 'stream.encoding.set'
  Required handlingError-handling middleware MUST catch this. Developer error — never call req.setEncoding().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[7]
• text · text-stream-not-readable

  error
  WhenRequest stream was already consumed by another middleware.
  ThrowsError with err.status === 500 and err.type === 'stream.not.readable'
  Required handlingError-handling middleware MUST catch this. Only one body parser should run per request.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilitycatastrophic
  Sources[8]

Sources

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

1. [1]expressjs.com/en/resourceshttps://expressjs.com/en/resources/middleware/body-parser.html
2. [2]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/issues/122
3. [3]vulert.com/vuln-db/debian-11-node-body-parser-170959https://vulert.com/vuln-db/debian-11-node-body-parser-170959
4. [4]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/lib/read.js
5. [5]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/README.md#unsupported-content-encoding-bogus
6. [6]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/README.md#request-size-did-not-match-content-length
7. [7]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/README.md#stream-encoding-should-not-be-set
8. [8]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/README.md#stream-is-not-readable
9. [9]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/security/advisories/GHSA-wqch-xfxh-vrr4
10. [10]github.com/expressjs/body-parserhttps://github.com/expressjs/body-parser/blob/master/README.md#the-input-exceeded-the-depth