transloadit/uppy · error · Error

Transloadit: The `params` option is required.

Error message

Transloadit: The `params` option is required.

What it means

validateParams throws when the Transloadit plugin's params option is entirely absent (null or undefined). 'params' carries the Assembly instructions (steps/templates) and auth key, so without it there is nothing to submit to Transloadit; the plugin fails fast during #prepareUpload (on upload-start) rather than sending an empty Assembly.

Source

Thrown at packages/@uppy/transloadit/src/index.ts:175

    transloadit?: { assembly: string }
    tus?: TusOpts<M, B>
  }
  export interface RemoteUppyFile<M extends Meta, B extends Body> {
    transloadit?: { assembly: string }
    tus?: TusOpts<M, B>
  }
}

const sendErrorToConsole = (originalErr: Error) => (err: Error) => {
  const error = new ErrorWithCause('Failed to send error to the client', {
    cause: err,
  })
  console.error(error, originalErr)
}

function validateParams(params?: AssemblyOptions['params']): void {
  if (params == null) {
    throw new Error('Transloadit: The `params` option is required.')
  }

  let parsed: AssemblyParameters
  if (typeof params === 'string') {
    try {
      parsed = JSON.parse(params) as AssemblyParameters
    } catch (err) {
      // Tell the user that this is not an Uppy bug!
      throw new ErrorWithCause(
        'Transloadit: The `params` option is a malformed JSON string.',
        { cause: err },
      )
    }
  } else {
    parsed = params
  }

  if (!parsed.auth?.key) {

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Provide params in the plugin options: params: { auth: { key }, steps: {...} } or a template_ids form
2. If params are computed per-upload, use getAssemblyOptions to return them per file/batch
3. Check for typos/casing in the option name (params, not Params/param)
4. Fail your config loading loudly if the template/params source is empty

Example fix

// before
uppy.use(Transloadit, { waitForEncoding: true }) // no params
await uppy.upload() // throws

// after
uppy.use(Transloadit, {
  params: {
    auth: { key: TRANSLOADIT_KEY },
    template_id: 'my-template',
  },
})

if (assemblyParams == null) {
  throw new Error('Transloadit params missing — check config')
}
uppy.use(Transloadit, { params: assemblyParams })

function hasParams(o: unknown): o is { params: Record<string, unknown> } {
  return typeof o === 'object' && o !== null && (o as any).params != null
}

try { await uppy.upload() }
catch (err) { if (/params.*option is required/.test(err.message)) fixTransloaditConfig() }

When it happens

Trigger: new Transloadit(uppy, {}) or { params: null } (or getAssemblyOptions returning no params), then calling uppy.upload(). #prepareUpload -> validateParams sees params == null and throws.

Common situations: Config built dynamically and the params assignment silently skipped; using assembly options fetched asynchronously that resolve to undefined; migrating from an older API where params was optional in some code paths; typo like Params or params nested one level too deep.

Related errors

• Transloadit: The `params` option is a malformed JSON string.
• Transloadit: The `params.auth.key` option is required. You c
• ThumbnailGenerator: The `lazy` and `waitForThumbnailsBeforeU
• Transloadit: Assembly status is missing `assembly_id`.
• Transloadit: Assembly status is missing ${label}.

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