Express Built‑in JSON Parsing: Limits, Errors, and Safe Migration

The problem: unexpected 413 responses on valid JSON

You POST a JSON payload to an Express 4.18 route and receive 413 Payload Too Large even though the body is only a few hundred kilobytes. The culprit is the default 100 KB limit baked into express.json(). Understanding that limit—and how to raise it without opening a denial‑of‑service vector—is the practical decision every Express developer faces.

How express.json() works

Since Express 4.16.0 the framework ships its own JSON body parser; the separate body-parser package is no longer required. The middleware:

• Matches requests whose Content-Type header is exactly application/json (configurable via the type option).
• Parses the request stream into a JavaScript object and attaches it to req.body.
• Enforces a default size limit of 100 KB. Larger bodies trigger a 413 error before your route runs.
• Emits a 400 Bad Request for malformed JSON, which propagates to any error‑handling middleware you have defined.

If you are on Express < 4.16.0 you must still npm install body-parser and use bodyParser.json(); the built‑in function simply does not exist.

Configuring the limit and accepted content types

Raise the limit with the limit option (string or number of bytes). Extend the matched content types with type (string, array, or function). Example:

const express = require('express');
const app = express();

// Accept JSON up to 1 MB and also application/*+json
app.use(express.json({
  limit: '1mb',               // 1 MB ≈ 1,048,576 bytes
  type: ['application/json', 'application/*+json']
}));

app.post('/webhook', (req, res) => {
  // req.body is now a parsed object
  console.log('Received:', req.body);
  res.status(202).send('accepted');
});

app.listen(3000, () => console.log('Listening on :3000'));

Run the server (requires Node ≥ 14 and write permission to the project directory). Then test with curl from a terminal that has network access to the host:

# Valid payload under the new limit
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"event":"order_created","payload":{"id":123}}'

# Payload larger than 100 KB but under 1 MB (should succeed)
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  --data-binary @large-payload.json

If the request exceeds the configured limit you will see a 413 response with the default Express HTML error page (or JSON if you have an error handler that sets Content-Type: application/json).

Trade‑offs and security considerations

Increasing limit expands the attack surface for request‑body‑based denial‑of‑service. Mitigate by:

• Placing a reverse proxy (nginx, Cloudflare, etc.) with its own client_max_body_size in front of Node.
• Applying rate limiting (e.g., express-rate-limit) on the same routes.
• Requiring authentication before the JSON parser runs (mount the parser on a sub‑router that is protected).

Remember that express.json() only handles JSON. For application/x-www-form-urlencoded use express.urlencoded({ extended: true }); for multipart uploads use a dedicated package such as multer.

Quick verification checklist

1. Confirm Express version: run node -e "console.log(require('express/package.json').version)" in the project root. You need ≥ 4.16.0.
2. Register the middleware exactly as shown above.
3. Send a valid JSON payload (≤ 100 KB) and verify req.body is populated.
4. Send a payload > 100 KB (e.g., a 200 KB file) and confirm a 413 response.
5. Raise the limit to '1mb', restart, and repeat step 4; the request should now succeed.
6. Send malformed JSON (e.g., {invalid) and ensure a 400 reaches your error handler.

If all checks pass, the parser is configured correctly for your workload.

Actionable closing

Start by verifying your Express version. Then add app.use(express.json({ limit: '1mb' })) (or whatever ceiling matches your legitimate maximum payload). Pair the higher limit with a reverse‑proxy body cap and a rate limiter. Finally, run the verification checklist above before deploying to production. This gives you predictable parsing behavior without re‑introducing the old body-parser dependency.