{"record":{"id":"f81f3263b6900e5f","repo":"transloadit/uppy","slug":"opts-formdata-must-be-true-when-opts-bundle-is","errorCode":null,"errorMessage":"`opts.formData` must be true when `opts.bundle` is enabled.","messagePattern":"`opts\\.formData` must be true when `opts\\.bundle` is enabled\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@uppy/xhr-upload/src/index.ts","lineNumber":185,"sourceCode":"  uploaderEvents: Record<string, EventManager<M, B> | null>\n\n  constructor(uppy: Uppy<M, B>, opts: XhrUploadOpts<M, B>) {\n    super(uppy, {\n      ...defaultOptions,\n      fieldName: opts.bundle ? 'files[]' : 'file',\n      ...opts,\n    })\n    this.type = 'uploader'\n    this.id = this.opts.id || 'XHRUpload'\n\n    this.defaultLocale = locale\n\n    this.i18nInit()\n\n    this.#queue = new TaskQueue({ concurrency: this.opts.limit })\n\n    if (this.opts.bundle && !this.opts.formData) {\n      throw new Error(\n        '`opts.formData` must be true when `opts.bundle` is enabled.',\n      )\n    }\n\n    if (this.opts.bundle && typeof this.opts.headers === 'function') {\n      throw new Error(\n        '`opts.headers` can not be a function when the `bundle: true` option is set.',\n      )\n    }\n\n    if (opts?.allowedMetaFields === undefined && 'metaFields' in this.opts) {\n      throw new Error(\n        'The `metaFields` option has been renamed to `allowedMetaFields`.',\n      )\n    }\n\n    this.uploaderEvents = Object.create(null)\n    /**","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/transloadit/uppy/blob/5d4dedd02a1ac0ae022c75c54aca76558f88e256/packages/@uppy/xhr-upload/src/index.ts#L167-L203","documentation":"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.","triggerScenarios":"new XHRUpload(uppy, { bundle: true, formData: false }) — enabling bundle while disabling formData.","commonSituations":"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.","solutions":["If you need bundling, keep formData true (default) and POST multipart/form-data","If you need formData: false (JSON/raw body), set bundle: false or omit it"],"exampleFix":"// before\nnew XHRUpload(uppy, { bundle: true, formData: false })\n// after\nnew XHRUpload(uppy, { bundle: true }) // formData defaults to true","handlingStrategy":"validation","validationCode":"if (opts.bundle && opts.formData === false) opts.bundle = false","typeGuard":"const isValidXhrConfig = (o: { bundle?: boolean; formData?: boolean }): boolean => !(o.bundle && o.formData === false)","tryCatchPattern":null,"preventionTips":["Decide upfront: multipart bundle vs single-request JSON body","Keep XHRUpload options in a typed object so TS catches inconsistencies"],"tags":["xhr-upload","bundle","form-data","invalid-config"],"backgroundTag":"conflicting-config-options","analyzedSha":"5d4dedd02a1ac0ae022c75c54aca76558f88e256","analyzedAt":"2026-08-28T12:18:41.267Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}