Fix PayloadTooLargeError: request entity too large in Express

This error occurs when the request body exceeds the size limit configured in Express's body-parser or express.json() middleware. The default limit is 100kb. Fix it by increasing the limit for routes that need larger payloads, adding a custom error handler for 413 responses, and validating payload sizes on the client side.

Reading the Stack Trace

Here's what each line means:

• at readStream (/app/node_modules/raw-body/index.js:155:17): The raw-body module detected the incoming stream exceeds the configured byte limit and threw PayloadTooLargeError.
• at jsonParser (/app/node_modules/body-parser/lib/types/json.js:135:5): The JSON body-parser middleware triggered the read which detected the oversized payload.
• at Layer.handle [as handle_request] (/app/node_modules/express/lib/router/layer.js:95:5): Express is executing the body-parser middleware layer which enforces the payload size limit.

Common Causes

const app = express();
app.use(express.json()); // Default 100kb limit

app.post('/api/import', (req, res) => {
  // Receives large JSON array with thousands of records
  res.json({ imported: req.body.length });
});

app.use(express.json({ limit: '100kb' })); // Same limit for all routes

app.post('/api/simple', handler); // 100kb is fine
app.post('/api/bulk-import', handler); // 100kb is too small

app.use(express.json({ limit: '1mb' }));

app.post('/api/data', (req, res) => {
  res.json({ received: true });
});

// No error handler for PayloadTooLargeError

The Fix

Set a reasonable default payload limit and override it per-route where larger payloads are expected. Add error-handling middleware that catches PayloadTooLargeError and returns a JSON response with the maximum allowed size.

const app = express();
app.use(express.json());

app.post('/api/import', (req, res) => {
  res.json({ imported: req.body.length });
});

app.listen(3000);

const app = express();

// Default limit for most routes
app.use(express.json({ limit: '1mb' }));

// Higher limit for specific routes that need it
app.post('/api/import', express.json({ limit: '10mb' }), (req, res) => {
  res.json({ imported: req.body.length });
});

// Error handler for oversized payloads
app.use((err, req, res, next) => {
  if (err.type === 'entity.too.large') {
    return res.status(413).json({
      error: 'Payload too large',
      maxSize: err.limit,
      message: 'The request body exceeds the maximum allowed size.'
    });
  }
  next(err);
});

app.listen(3000);

Testing the Fix

const request = require('supertest');
const express = require('express');

function createApp() {
  const app = express();
  app.use(express.json({ limit: '1kb' })); // Small limit for testing
  app.post('/api/data', (req, res) => res.json({ received: true }));
  app.use((err, req, res, next) => {
    if (err.type === 'entity.too.large') {
      return res.status(413).json({ error: 'Payload too large' });
    }
    next(err);
  });
  return app;
}

describe('Payload size limits', () => {
  it('accepts payloads under the limit', async () => {
    const res = await request(createApp())
      .post('/api/data')
      .send({ small: 'data' });
    expect(res.status).toBe(200);
    expect(res.body.received).toBe(true);
  });

  it('returns 413 for payloads over the limit', async () => {
    const largePayload = { data: 'x'.repeat(2000) };
    const res = await request(createApp())
      .post('/api/data')
      .send(largePayload);
    expect(res.status).toBe(413);
    expect(res.body.error).toBe('Payload too large');
  });
});

Run your tests:

npx jest --testPathPattern=payload

Pushing Through CI/CD

git checkout -b fix/express-payload-too-large,git add src/app.js src/__tests__/payload.test.js,git commit -m "fix: configure per-route payload limits and 413 error handler",git push origin fix/express-payload-too-large

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npx jest --coverage
      - run: npm run lint

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to confirm payload limits work correctly for all routes.
2. Open a pull request with the payload limit configuration changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify large payloads are handled in staging before promoting to production.

Frequently Asked Questions