Get and validate the raw body of a readable stream
Latest commit 4f49844 Jul 7, 2016 @dougwilson dougwilson build: Node.js@6.3


NPM Version NPM Downloads Node.js Version Build status Test coverage

Gets the entire buffer of a stream either as a Buffer or a string. Validates the stream's length against an expected length and maximum limit. Ideal for parsing request bodies.


var getRawBody = require('raw-body')

getRawBody(stream, [options], [callback])

Returns a promise if no callback specified and global Promise exists.


  • length - The length of the stream. If the contents of the stream do not add up to this length, an 400 error code is returned.
  • limit - The byte limit of the body. If the body ends up being larger than this limit, a 413 error code is returned.
  • encoding - The requested encoding. By default, a Buffer instance will be returned. Most likely, you want utf8. You can use any type of encoding supported by iconv-lite.

You can also pass a string in place of options to just specify the encoding.

callback(err, res):

  • err - the following attributes will be defined if applicable:

    • limit - the limit in bytes
    • length and expected - the expected length of the stream
    • received - the received bytes
    • encoding - the invalid encoding
    • status and statusCode - the corresponding status code for the error
    • type - either entity.too.large, request.aborted, request.size.invalid, stream.encoding.set, or encoding.unsupported
  • res - the result, either as a String if an encoding was set or a Buffer otherwise.

If an error occurs, the stream will be paused, everything unpiped, and you are responsible for correctly disposing the stream. For HTTP requests, no handling is required if you send a response. For streams that use file descriptors, you should stream.destroy() or stream.close() to prevent leaks.


Simple Express example

var contentType = require('content-type')
var getRawBody = require('raw-body')

app.use(function (req, res, next) {
  getRawBody(req, {
    length: req.headers['content-length'],
    limit: '1mb',
    encoding: contentType.parse(req).parameters.charset
  }, function (err, string) {
    if (err) return next(err)
    req.text = string

Simple Koa example

var contentType = require('content-type')
var getRawBody = require('raw-body')

app.use(function * (next) {
  this.text = yield getRawBody(this.req, {
    length: this.req.headers['content-length'],
    limit: '1mb',
    encoding: contentType.parse(this.req).parameters.charset
  yield next

Using as a promise

To use this library as a promise, simply omit the callback and a promise is returned, provided that a global Promise is defined.

var getRawBody = require('raw-body')
var http = require('http')

var server = http.createServer(function (req, res) {
  .then(function (buf) {
    res.statusCode = 200
    res.end(buf.length + ' bytes submitted')
  .catch(function (err) {
    res.statusCode = 500