transloadit/uppy · error · Error

`opts.formData` must be true when `opts.bundle` is enabled.

Error message

`opts.formData` must be true when `opts.bundle` is enabled.

What it means

XHRUpload throws in its constructor when bundle is enabled but formData is falsy. Bundled uploads POST all files together as a single multipart/form-data request, which is impossible with a JSON/binary body, so the combination is rejected up front.

Source

Thrown at packages/@uppy/xhr-upload/src/index.ts:185

  uploaderEvents: Record<string, EventManager<M, B> | null>

  constructor(uppy: Uppy<M, B>, opts: XhrUploadOpts<M, B>) {
    super(uppy, {
      ...defaultOptions,
      fieldName: opts.bundle ? 'files[]' : 'file',
      ...opts,
    })
    this.type = 'uploader'
    this.id = this.opts.id || 'XHRUpload'

    this.defaultLocale = locale

    this.i18nInit()

    this.#queue = new TaskQueue({ concurrency: this.opts.limit })

    if (this.opts.bundle && !this.opts.formData) {
      throw new Error(
        '`opts.formData` must be true when `opts.bundle` is enabled.',
      )
    }

    if (this.opts.bundle && typeof this.opts.headers === 'function') {
      throw new Error(
        '`opts.headers` can not be a function when the `bundle: true` option is set.',
      )
    }

    if (opts?.allowedMetaFields === undefined && 'metaFields' in this.opts) {
      throw new Error(
        'The `metaFields` option has been renamed to `allowedMetaFields`.',
      )
    }

    this.uploaderEvents = Object.create(null)
    /**

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. If you need bundling, keep formData true (default) and POST multipart/form-data
2. If you need formData: false (JSON/raw body), set bundle: false or omit it

Example fix

// before
new XHRUpload(uppy, { bundle: true, formData: false })
// after
new XHRUpload(uppy, { bundle: true }) // formData defaults to true

if (opts.bundle && opts.formData === false) opts.bundle = false

const isValidXhrConfig = (o: { bundle?: boolean; formData?: boolean }): boolean => !(o.bundle && o.formData === false)

When it happens

Trigger: new XHRUpload(uppy, { bundle: true, formData: false }) — enabling bundle while disabling formData.

Common situations: Configuring XHRUpload for a JSON endpoint and then turning on bundle to upload files in one request; tweaking options objects where formData was previously set false.

Related errors

• fieldname must be a string

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