Koa Body Parser

Common errors

• HTTP 413 Payload Too Large

  cause The request body size exceeded the configured limit for its content type.
  fix Increase `jsonLimit`, `formLimit`, `textLimit`, or `xmlLimit` options in the `bodyParser` middleware or ensure client requests adhere to limits. Example: `bodyParser({ jsonLimit: '5mb' })`.

• Error: body parse error

  cause The request body was malformed for the specified `Content-Type`, or the `onerror` option caught a parsing error.
  fix Check the `Content-Type` header matches the actual body format (e.g., `application/json` for JSON). Review the client-side data being sent. Implement custom `onerror` to log details: `bodyParser({ onerror: (err, ctx) => { console.error('Parsing failed:', err); ctx.throw(422, 'Invalid body format'); } })`.

• Cannot read property 'body' of undefined

  cause Attempting to access `ctx.request.body` before `koa-bodyparser` has been applied or for a request method that typically doesn't have a body (GET, HEAD, DELETE) and no body was sent.
  fix Ensure `app.use(bodyParser());` is called *before* any route handlers that access `ctx.request.body`. Remember that GET/HEAD/DELETE requests typically don't have bodies; `ctx.request.body` will be an empty object if no body was parsed. Also, `parsedMethods` option (if using `@koa/bodyparser`) can restrict which methods are parsed.

• TypeError: app.use() requires a middleware function but got a undefined

  cause The `bodyParser` function was not called when passed to `app.use()`, or there was an issue with the import.
  fix Ensure `bodyParser` is called as a function: `app.use(bodyParser());`. If using CommonJS, verify `const bodyParser = require('koa-bodyparser');`.

Warnings

• breaking Starting with `v6.1.0`, the TypeScript type for `Koa.Request.body` changed from `any` to `unknown`. This change enhances type safety but may require existing TypeScript applications to add type assertions or narrow the type of `ctx.request.body`.
  Fix: Update TypeScript code to handle `unknown` type for `ctx.request.body` explicitly, e.g., `(ctx.request.body as { someField: string }).someField` or `if (typeof ctx.request.body === 'object' && ctx.request.body !== null) { /* type narrowing */ }`.
• breaking For Koa v1.x applications, `koa-bodyparser` v3.x and newer are not compatible. You must use `koa-bodyparser@2.x` to maintain compatibility with Koa v1.x.
  Fix: For Koa v1.x, install `npm install koa-bodyparser@2 --save`. For Koa v2+, use the latest version.
• gotcha This module explicitly does *not* support parsing `multipart/form-data` (file uploads). Attempting to use it for multipart data will result in incorrect parsing or errors.
  Fix: For `multipart/form-data`, use a dedicated middleware like `@koa/multer` or `koa-body` (not `koa-bodyparser`).
• gotcha By default, `koa-bodyparser` will only parse `json` and `form` body types. If you need to parse `text` or `xml` bodies, you must explicitly enable them using the `enableTypes` option.
  Fix: Configure `enableTypes`: `app.use(bodyParser({ enableTypes: ['json', 'form', 'text', 'xml'] }));`
• gotcha Body size limits (`jsonLimit`, `formLimit`, `textLimit`, `xmlLimit`) can lead to HTTP 413 (Payload Too Large) errors if the incoming body exceeds the configured limits. Defaults are `1mb` for JSON/text/XML and `56kb` for URL-encoded forms.
  Fix: Adjust limits in options: `app.use(bodyParser({ jsonLimit: '10mb', formLimit: '5mb' }));`. Inform users of potential size constraints.

Install

• npm install koa-bodyparser npm
• yarn add koa-bodyparser yarn
• pnpm add koa-bodyparser pnpm

Imports

• bodyParser
  wrong:

  const bodyParser = require('koa-bodyparser');

  correct:

  import bodyParser from 'koa-bodyparser';

  While CommonJS `require` is shown in older READMEs, modern Koa projects primarily use ESM `import`.
• bodyParser.Options

  import type { Options } from 'koa-bodyparser';

  Importing types explicitly using `import type` is best practice in TypeScript.
• bodyParser middleware
  wrong:

  app.use(bodyParser);

  correct:

  app.use(bodyParser());

  The `bodyParser` function returns a Koa middleware, so it must be called (e.g., `bodyParser()`) even without options. Passing the function directly will not initialize the middleware correctly.

Quickstart

This quickstart demonstrates how to integrate koa-bodyparser into a Koa application to parse incoming JSON and form-encoded request bodies, and how to access the parsed data on `ctx.request.body`.

import Koa from 'koa';
import bodyParser from 'koa-bodyparser';

const app = new Koa();

// Apply the body parser middleware globally
app.use(bodyParser({
  jsonLimit: '5mb',
  formLimit: '10mb',
  textLimit: '2mb',
  onerror: (err, ctx) => {
    console.error('Body parse error:', err);
    ctx.throw(422, 'Cannot parse request body. Ensure correct Content-Type and format.');
  }
}));

app.use(async ctx => {
  if (ctx.method === 'POST' || ctx.method === 'PUT' || ctx.method === 'PATCH') {
    // The parsed body is available at ctx.request.body
    // If no body was parsed (e.g., GET request), it will be an empty object {}
    console.log('Received body:', ctx.request.body);
    ctx.status = 200;
    ctx.body = { received: ctx.request.body };
  } else {
    ctx.body = 'Send a POST, PUT, or PATCH request with a body.';
  }
});

const port = process.env.PORT ?? 3000;
app.listen(port, () => {
  console.log(`Server listening on http://localhost:${port}`);
});