transloadit/uppy · error · RestrictionError

missingRequiredMetaField

Error message

missingRequiredMetaField

What it means

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.

Source

Thrown at packages/@uppy/core/src/Uppy.ts:2392

      throw new Error(
        'Not starting the upload because onBeforeUpload returned false',
      )
    }

    if (onBeforeUploadResult && typeof onBeforeUploadResult === 'object') {
      files = onBeforeUploadResult
      // Updating files in state, because uploader plugins receive file IDs,
      // and then fetch the actual file object from state
      this.setState({
        files,
      })
    }

    try {
      this.#restricter.validateMinNumberOfFiles(files)

      if (!this.#checkRequiredMetaFields(files)) {
        throw new RestrictionError(this.i18n('missingRequiredMetaField'))
      }

      const { currentUploads } = this.getState()
      // get a list of files that are currently assigned to uploads
      const currentlyUploadingFiles = Object.values(currentUploads).flatMap(
        (curr) => curr.fileIDs,
      )

      const waitingFileIDs = Object.keys(files).filter((fileID) => {
        const file = this.getFile(fileID)
        // if the file hasn't started uploading and hasn't already been assigned to an upload..
        return (
          file &&
          !file.progress.uploadStarted &&
          !currentlyUploadingFiles.includes(fileID)
        )
      })

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. 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
2. Check readiness before upload: const missing = uppy.getState().files[fileId].missingRequiredMetaFields; if any file has entries, block the upload button
3. Set the meta programmatically before uploading: uppy.setFileMeta(fileId, {caption: '...'})
4. If the field is not actually mandatory, remove it from restrictions.requiredMetaFields

Example fix

// before
const restrictions = { requiredMetaFields: ['caption'] }
// user clicks upload with empty caption -> RestrictionError thrown

// after
uppy.on('restriction-failed', (file, error) => {
  if (error.message === uppy.i18n('missingRequiredMetaField')) {
    uppy.info('Please fill in the required fields', 'error', 4000)
    dashboard.openFileEditor(file) // let user complete metadata
  }
})

const files = Object.values(uppy.getState().files)
const notReady = files.filter((f) => (f.missingRequiredMetaFields ?? []).length > 0)
if (notReady.length > 0) {
  uppy.info('Please fill in required metadata', 'error', 4000)
  // disable upload / open editor instead of uploading
} else {
  await uppy.upload()
}

null

uppy.on('restriction-failed', (file, error) => {
  if (error.message === uppy.i18n('missingRequiredMetaField')) {
    dashboard.openFileEditor(file)
  }
})

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• metadata must be an object
• region must be a string
• [s3mini] key must be a non-empty string
• [s3mini] uploadId must be a non-empty string
• [s3mini] partNumber must be a positive integer

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