vercel/next.js · error · Error

maxPostponedStateSize must be a valid number (bytes) or file

Error message

maxPostponedStateSize must be a valid number (bytes) or filesize format string (e.g., "5mb")

What it means

Thrown by getMaxPostponedStateSize when the experimental.experimental.maxPostponedStateSize config value cannot be parsed into bytes by the bytes library (parseSizeLimit returns undefined). The value must be a positive number (bytes) or a filesize string like '5mb'.

Source

Thrown at packages/next/src/server/lib/postponed-request-body.ts:25

const INVALID_MAX_POSTPONED_STATE_SIZE_ERROR_MESSAGE =
  'maxPostponedStateSize must be a valid number (bytes) or filesize format string (e.g., "5mb")'

export type PostponedRequestBodyChunk = Buffer | Uint8Array | string

export function getMaxPostponedStateSize(
  configuredMaxPostponedStateSize: SizeLimit | undefined
): {
  maxPostponedStateSize: SizeLimit
  maxPostponedStateSizeBytes: number
} {
  const maxPostponedStateSize =
    configuredMaxPostponedStateSize ?? DEFAULT_MAX_POSTPONED_STATE_SIZE
  const maxPostponedStateSizeBytes = parseMaxPostponedStateSize(
    configuredMaxPostponedStateSize
  )

  if (maxPostponedStateSizeBytes === undefined) {
    throw new Error(INVALID_MAX_POSTPONED_STATE_SIZE_ERROR_MESSAGE)
  }

  return { maxPostponedStateSize, maxPostponedStateSizeBytes }
}

export function getPostponedStateExceededErrorMessage(
  maxPostponedStateSize: SizeLimit
): string {
  return (
    `Postponed state exceeded ${maxPostponedStateSize} limit. ` +
    `To configure the limit, see: https://nextjs.org/docs/app/api-reference/config/next-config-js/max-postponed-state-size`
  )
}

function toBuffer(chunk: PostponedRequestBodyChunk): Buffer {
  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
}

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Set experimental.maxPostponedStateSize to a valid filesize string like '100mb' or a positive byte number.
2. Remove the option entirely to use the default (100 MB).
3. Verify the unit is supported by the bytes library (b, kb, mb, gb, tb).

Example fix

// before
module.exports = {
  experimental: { maxPostponedStateSize: 'lots' }, // unparseable
}

// after
module.exports = {
  experimental: { maxPostponedStateSize: '100mb' },
}

const bytes = require('bytes')
function validateMaxPostponedSize(v: unknown): void {
  const n = bytes.parse(v)
  if (n === null || isNaN(n) || n < 1) throw new Error('Invalid maxPostponedStateSize')
}

function isValidSizeLimit(v: unknown): v is string | number {
  if (typeof v === 'number') return v >= 1
  if (typeof v === 'string') {
    const n = require('bytes').parse(v)
    return n !== null && !isNaN(n) && n >= 1
  }
  return false
}

null

When it happens

Trigger: next.config.js sets experimental.maxPostponedStateSize to an unparseable value such as 'abc', an empty string, 0, or a negative number. The bytes parser returns null/NaN/<1 and parseMaxPostponedStateSize returns undefined.

Common situations: Typo in the size string, using a unit bytes doesn't recognize, or passing a non-numeric value. Encountered at server boot when PPR/postponed state handling initializes.

Related errors

• `forbidden()` is experimental and only allowed to be enabled
• `unauthorized()` is experimental and only allowed to be used
• Could not parse output from TypeScript's --showConfig.
• The experimental.allowDevelopmentBuild option requires NODE_
• `experimental.cssChunking: "graph"` is only supported with T

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/e39622fbb6530d1a. Report an issue: GitHub.