transloadit/uppy · error · Error

The `metaFields` option has been renamed to `allowedMetaFiel

Error message

The `metaFields` option has been renamed to `allowedMetaFields`.

What it means

The Tus plugin's constructor throws immediately when it detects the removed metaFields option. The option was renamed to allowedMetaFields, and the explicit error exists to fail fast instead of silently ignoring your metadata field selection.

Source

Thrown at packages/@uppy/tus/src/index.ts:139

  B
> {
  static VERSION = packageJson.version

  #retryDelayIterator

  requests: RateLimitedQueue

  uploaders: Record<string, tus.Upload | null>

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

  constructor(uppy: Uppy<M, B>, opts: TusOpts<M, B>) {
    super(uppy, { ...defaultOptions, ...opts })
    this.type = 'uploader'
    this.id = this.opts.id || 'Tus'

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

    if ('autoRetry' in opts) {
      throw new Error(
        'The `autoRetry` option was deprecated and has been removed.',
      )
    }

    /**
     * Simultaneous upload limiting is shared across all uploads with this plugin.
     *
     * @type {RateLimitedQueue}
     */
    this.requests =
      this.opts.rateLimitedQueue ?? new RateLimitedQueue(this.opts.limit)
    this.#retryDelayIterator = this.opts.retryDelays?.values()

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Rename metaFields to allowedMetaFields in your Tus options
2. Remove any leftover metaFields keys in shared/config objects

Example fix

// before
new Tus(uppy, { metaFields: ['caption', 'license'] })
// after
new Tus(uppy, { allowedMetaFields: ['caption', 'license'] })

const tusOpts = { ...legacy };
delete tusOpts.metaFields;
// then migrate
const normalized = 'metaFields' in tusOpts
  ? { allowedMetaFields: tusOpts.metaFields, ...tusOpts }
  : tusOpts

const hasRenamedOption = (o: object): o is { metaFields: unknown } => 'metaFields' in o

When it happens

Trigger: Instantiating new Tus(uppy, { metaFields: [...] }) or passing any opts object with a metaFields key while not setting allowedMetaFields.

Common situations: Upgrading from an old Uppy version (pre-rename) without migrating plugin options; copy-pasted legacy snippets or tutorials.

Related errors

• The Provider option "providerOptions.${deprecated}" is no lo
• The `autoRetry` option was deprecated and has been removed.
• Invalid encrypted value. Maybe it was generated with an old
• Cannot mark a queued request as done: this indicates a bug
• File data is empty

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