transloadit/uppy · error · ValidationError

maxFileSize exceeded

Error message

maxFileSize exceeded

What it means

The file size passed to Uploader exceeds companionOptions.maxFileSize, so the upload is rejected before it starts. exceedsMaxFileSize compares options.size against the configured limit.

Source

Thrown at packages/@uppy/companion/src/server/Uploader.ts:122

export class ValidationError extends Error {
  override name = 'ValidationError'
}

function validateOptions(options: UploaderOptions): void {
  // validate HTTP Method (optional)
  if (options.httpMethod) {
    if (typeof options.httpMethod !== 'string') {
      throw new ValidationError('unsupported HTTP METHOD specified')
    }

    const method = options.httpMethod.toUpperCase()
    if (method !== 'PUT' && method !== 'POST') {
      throw new ValidationError('unsupported HTTP METHOD specified')
    }
  }

  if (exceedsMaxFileSize(options.companionOptions.maxFileSize, options.size)) {
    throw new ValidationError('maxFileSize exceeded')
  }

  // validate fieldname (optional)
  if (options.fieldname != null && typeof options.fieldname !== 'string') {
    throw new ValidationError('fieldname must be a string')
  }

  // validate metadata (optional)
  if (options.metadata != null && typeof options.metadata !== 'object') {
    throw new ValidationError('metadata must be an object')
  }

  // validate headers (optional)
  if (options.headers != null && typeof options.headers !== 'object') {
    throw new ValidationError('headers must be an object')
  }

  // validate protocol (optional)

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Raise maxFileSize in the Companion options to accommodate the file
2. Enforce the same limit client-side so users see the error early
3. If unlimited uploads are intended, set maxFileSize: -1 (or omit it)

Example fix

// before
companionOptions: { maxFileSize: 10_000_000 }

// after
companionOptions: { maxFileSize: 100_000_000 }

const max = companionOptions.maxFileSize
if (max != null && max >= 0 && size > max) throw new Error('file too large')

const exceeds = (size: number, max?: number) => max != null && max >= 0 && size > max

try { new Uploader(opts) } catch (e) { if (e instanceof ValidationError && /maxFileSize/.test(e.message)) return rejectFile(); throw e }

When it happens

Trigger: new Uploader({ size: 50_000_000, companionOptions: { maxFileSize: 10_000_000 } }) — any size above the configured maxFileSize (a maxFileSize of -1/undefined means unlimited).

Common situations: Users selecting large files while the server default or explicit maxFileSize is lower; frontend limits not matching backend limits after a config change.

Related errors

• unsupported HTTP METHOD specified
• fieldname must be a string
• metadata must be an object
• headers must be an object
• unsupported protocol specified

AI-assisted analysis of transloadit/uppy@5d4dedd02a (2026-08-28). Data as JSON: /api/errors/2a05d5600e30f418. Report an issue: GitHub.