transloadit/uppy · error · Error

Transloadit: The `params.auth.key` option is required. You c

Error message

Transloadit: The `params.auth.key` option is required. You can find your Transloadit API key at https://transloadit.com/c/template-credentials

What it means

validateParams requires params.auth.key (the Transloadit API key) even when params parses fine or is an object. Without the auth key, no Assembly can be authenticated with Transloadit; the plugin throws before upload with a message pointing to where to find the key.

Source

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

  }

  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) {
    throw new Error(
      'Transloadit: The `params.auth.key` option is required. ' +
        'You can find your Transloadit API key at https://transloadit.com/c/template-credentials',
    )
  }
}

function ensureAssemblyId(status: AssemblyResponse): string {
  if (!status.assembly_id) {
    console.warn('Assembly status is missing `assembly_id`.', status)
    throw new Error('Transloadit: Assembly status is missing `assembly_id`.')
  }
  return status.assembly_id
}

function ensureUrl(
  label: string,
  ...candidates: Array<string | undefined>
): string {

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Add auth.key to params: params: { auth: { key: 'your-key' }, ... }
2. If you don't want the key in the browser, use getAssemblyOptions to fetch signed params (auth.key + expires + signature) from your backend per upload
3. Verify the env variable actually resolves (log it at startup) — undefined silently omits the key
4. For template users, ensure the API key from https://transloadit.com/c/template-credentials is the one configured

Example fix

// before
uppy.use(Transloadit, {
  params: { template_id: 'xxx' }, // no auth.key
})

// after
uppy.use(Transloadit, {
  getAssemblyOptions: () =>
    fetch('/api/transloadit-params').then((r) => r.json()), // returns { params: { auth: { key, expires, signature }, ... } }
})

const { auth } = params
if (!auth?.key) {
  throw new Error('Missing TRANSLOADIT auth.key — fetch signed params from backend')
}

function hasAuthKey(p: unknown): p is { auth: { key: string } } {
  return typeof (p as any)?.auth?.key === 'string' && (p as any).auth.key.length > 0
}

try { await uppy.upload() }
catch (err) { if (/auth\.key.*required/.test(err.message)) await injectSignedParamsViaGetAssemblyOptions() }

When it happens

Trigger: Passing params: { steps: {...} } (no auth), or a template-only form like { template_id } without auth.key (note: when using template_id with signed workflows the key is still required client-side unless getAssemblyOptions injects it), then uploading.

Common situations: Key stored in a backend and meant to be injected via getAssemblyOptions but the injection never runs; using signed Assembly URLs (signature) and assuming the key isn't needed; env var name typo (TRANSLOADIT_API_KEY vs TRANSLOADIT_KEY) yielding undefined.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• Transloadit: The `params` option is required.
• Transloadit: The `params` option is a malformed JSON string.
• Invalid token payload: expected string
• ThumbnailGenerator: The `lazy` and `waitForThumbnailsBeforeU
• Transloadit: Assembly status is missing `assembly_id`.

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