{"record":{"id":"fd569601d90f644a","repo":"transloadit/uppy","slug":"missingrequiredmetafield","errorCode":null,"errorMessage":"missingRequiredMetaField","messagePattern":"missingRequiredMetaField","errorType":"validation","errorClass":"RestrictionError","httpStatus":null,"severity":"error","filePath":"packages/@uppy/core/src/Uppy.ts","lineNumber":2392,"sourceCode":"      throw new Error(\n        'Not starting the upload because onBeforeUpload returned false',\n      )\n    }\n\n    if (onBeforeUploadResult && typeof onBeforeUploadResult === 'object') {\n      files = onBeforeUploadResult\n      // Updating files in state, because uploader plugins receive file IDs,\n      // and then fetch the actual file object from state\n      this.setState({\n        files,\n      })\n    }\n\n    try {\n      this.#restricter.validateMinNumberOfFiles(files)\n\n      if (!this.#checkRequiredMetaFields(files)) {\n        throw new RestrictionError(this.i18n('missingRequiredMetaField'))\n      }\n\n      const { currentUploads } = this.getState()\n      // get a list of files that are currently assigned to uploads\n      const currentlyUploadingFiles = Object.values(currentUploads).flatMap(\n        (curr) => curr.fileIDs,\n      )\n\n      const waitingFileIDs = Object.keys(files).filter((fileID) => {\n        const file = this.getFile(fileID)\n        // if the file hasn't started uploading and hasn't already been assigned to an upload..\n        return (\n          file &&\n          !file.progress.uploadStarted &&\n          !currentlyUploadingFiles.includes(fileID)\n        )\n      })\n","sourceCodeStart":2374,"sourceCodeEnd":2410,"githubUrl":"https://github.com/transloadit/uppy/blob/5d4dedd02a1ac0ae022c75c54aca76558f88e256/packages/@uppy/core/src/Uppy.ts#L2374-L2410","documentation":"Thrown by Uppy.validateRestrictions during the upload phase when one or more selected files are missing metadata fields declared as required via the requiredMetaFields restriction option. The error message is localized (i18n key 'missingRequiredMetaField') and wrapped in a RestrictionError. It exists to prevent uploads that a backend would reject because mandatory metadata (e.g. caption, license, department) is absent.","triggerScenarios":"Calling uppy.upload() (or uppy.addFiles followed by upload) while a file's meta object lacks one or more keys listed in restrictions.requiredMetaFields. #checkRequiredMetaFields(files) returns false and the RestrictionError is thrown inside the upload flow.","commonSituations":"A Dashboard UI lets the user click Upload before filling in required meta fields; requiredMetaFields was added/changed but the UI form was not updated; files added programmatically via uppy.addFile() without setting meta; using a custom UI that never surfaces the onrestrictionfailed event so the throw surfaces as an unhandled rejection.","solutions":["Listen to the 'restriction-failed' (onrestrictionfailed) event and prompt the user to fill in the missing fields (e.g. open Dashboard file card edit mode) before retrying the upload","Check readiness before upload: const missing = uppy.getState().files[fileId].missingRequiredMetaFields; if any file has entries, block the upload button","Set the meta programmatically before uploading: uppy.setFileMeta(fileId, {caption: '...'})","If the field is not actually mandatory, remove it from restrictions.requiredMetaFields"],"exampleFix":"// before\nconst restrictions = { requiredMetaFields: ['caption'] }\n// user clicks upload with empty caption -> RestrictionError thrown\n\n// after\nuppy.on('restriction-failed', (file, error) => {\n  if (error.message === uppy.i18n('missingRequiredMetaField')) {\n    uppy.info('Please fill in the required fields', 'error', 4000)\n    dashboard.openFileEditor(file) // let user complete metadata\n  }\n})","handlingStrategy":"validation","validationCode":"const files = Object.values(uppy.getState().files)\nconst notReady = files.filter((f) => (f.missingRequiredMetaFields ?? []).length > 0)\nif (notReady.length > 0) {\n  uppy.info('Please fill in required metadata', 'error', 4000)\n  // disable upload / open editor instead of uploading\n} else {\n  await uppy.upload()\n}","typeGuard":"null","tryCatchPattern":"uppy.on('restriction-failed', (file, error) => {\n  if (error.message === uppy.i18n('missingRequiredMetaField')) {\n    dashboard.openFileEditor(file)\n  }\n})","preventionTips":["Always handle 'restriction-failed' when using requiredMetaFields","Disable the Upload button while any file has missingRequiredMetaFields entries","Set required meta via setFileMeta immediately when adding files programmatically"],"tags":["uppy","validation","metadata","restrictions","i18n"],"backgroundTag":"client-side-validation-failed","analyzedSha":"5d4dedd02a1ac0ae022c75c54aca76558f88e256","analyzedAt":"2026-08-28T12:18:41.267Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}