vercel/next.js · error

Client Max Body Size must be a valid number (bytes) or files

Error message

Client Max Body Size must be a valid number (bytes) or filesize format string (e.g., "5mb")

What it means

`experimental.proxyClientMaxBodySize` is normalized at config.ts:1057-1071. It accepts either a string (parsed via `bytes.parse`) or a number (bytes). Any other type (boolean, object, null-as-not-undefined is fine but a function/array/etc.) throws this error before normalization proceeds.

Source

Thrown at packages/next/src/server/config.ts:1068

    userConfig.skipProxyUrlNormalize !== undefined &&
    userConfig.skipMiddlewareUrlNormalize === undefined
  ) {
    result.skipMiddlewareUrlNormalize = userConfig.skipProxyUrlNormalize
  }

  // Normalize & validate experimental.proxyClientMaxBodySize
  if (typeof result.experimental?.proxyClientMaxBodySize !== 'undefined') {
    const proxyClientMaxBodySize = result.experimental.proxyClientMaxBodySize
    let normalizedValue: number

    if (typeof proxyClientMaxBodySize === 'string') {
      const bytes =
        require('next/dist/compiled/bytes') as typeof import('next/dist/compiled/bytes')
      normalizedValue = bytes.parse(proxyClientMaxBodySize)
    } else if (typeof proxyClientMaxBodySize === 'number') {
      normalizedValue = proxyClientMaxBodySize
    } else {
      throw new Error(
        'Client Max Body Size must be a valid number (bytes) or filesize format string (e.g., "5mb")'
      )
    }

    if (isNaN(normalizedValue) || normalizedValue < 1) {
      throw new Error('Client Max Body Size must be larger than 0 bytes')
    }

    // Store the normalized value as a number
    result.experimental.proxyClientMaxBodySize = normalizedValue
  }

  warnOptionHasBeenMovedOutOfExperimental(
    result,
    'transpilePackages',
    'transpilePackages',
    configFileName,
    silent

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Set the value to a number of bytes or a filesize string: `proxyClientMaxBodySize: 5_242_880` or `proxyClientMaxBodySize: '5mb'`.
2. If reading from an env var, coerce explicitly: `proxyClientMaxBodySize: process.env.MAX_BODY ? Number(process.env.MAX_BODY) : undefined`.
3. Omit the key entirely to use the default.

Example fix

// before
module.exports = { experimental: { proxyClientMaxBodySize: true } }
// after
module.exports = { experimental: { proxyClientMaxBodySize: '5mb' } }

const v = config.experimental?.proxyClientMaxBodySize;
if (v !== undefined && typeof v !== 'number' && typeof v !== 'string') {
  throw new Error('proxyClientMaxBodySize must be number or filesize string');
}

function isBodySizeInput(v: unknown): v is number | string {
  return typeof v === 'number' || typeof v === 'string';
}

When it happens

Trigger: Setting `experimental.proxyClientMaxBodySize: true`, `proxyClientMaxBodySize: ['5mb']`, or `proxyClientMaxBodySize: { size: 5 }`.

Common situations: Accidentally wrapping the value in an array or object from a templated config generator. Passing a boolean from an env-var coercion (`!!process.env.X`).

Related errors

• Client Max Body Size must be larger than 0 bytes
• Server Actions Size Limit must be a valid number or filesize
• Config options `experimental.proxyClientMaxBodySize` and `ex
• Config options `experimental.proxyPrefetch` and `experimenta
• Config options `experimental.externalProxyRewritesResolve` a

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