{"record":{"id":"6696c96ef6d3b18c","repo":"transloadit/uppy","slug":"transloadit-the-params-auth-key-option-is-requi","errorCode":null,"errorMessage":"Transloadit: The `params.auth.key` option is required. You can find your Transloadit API key at https://transloadit.com/c/template-credentials","messagePattern":"Transloadit: The `params\\.auth\\.key` option is required\\. You can find your Transloadit API key at https://transloadit\\.com/c/template-credentials","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@uppy/transloadit/src/index.ts","lineNumber":194,"sourceCode":"  }\n\n  let parsed: AssemblyParameters\n  if (typeof params === 'string') {\n    try {\n      parsed = JSON.parse(params) as AssemblyParameters\n    } catch (err) {\n      // Tell the user that this is not an Uppy bug!\n      throw new ErrorWithCause(\n        'Transloadit: The `params` option is a malformed JSON string.',\n        { cause: err },\n      )\n    }\n  } else {\n    parsed = params\n  }\n\n  if (!parsed.auth?.key) {\n    throw new Error(\n      'Transloadit: The `params.auth.key` option is required. ' +\n        'You can find your Transloadit API key at https://transloadit.com/c/template-credentials',\n    )\n  }\n}\n\nfunction ensureAssemblyId(status: AssemblyResponse): string {\n  if (!status.assembly_id) {\n    console.warn('Assembly status is missing `assembly_id`.', status)\n    throw new Error('Transloadit: Assembly status is missing `assembly_id`.')\n  }\n  return status.assembly_id\n}\n\nfunction ensureUrl(\n  label: string,\n  ...candidates: Array<string | undefined>\n): string {","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/transloadit/uppy/blob/5d4dedd02a1ac0ae022c75c54aca76558f88e256/packages/@uppy/transloadit/src/index.ts#L176-L212","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add auth.key to params: params: { auth: { key: 'your-key' }, ... }","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","Verify the env variable actually resolves (log it at startup) — undefined silently omits the key","For template users, ensure the API key from https://transloadit.com/c/template-credentials is the one configured"],"exampleFix":"// before\nuppy.use(Transloadit, {\n  params: { template_id: 'xxx' }, // no auth.key\n})\n\n// after\nuppy.use(Transloadit, {\n  getAssemblyOptions: () =>\n    fetch('/api/transloadit-params').then((r) => r.json()), // returns { params: { auth: { key, expires, signature }, ... } }\n})","handlingStrategy":"validation","validationCode":"const { auth } = params\nif (!auth?.key) {\n  throw new Error('Missing TRANSLOADIT auth.key — fetch signed params from backend')\n}","typeGuard":"function hasAuthKey(p: unknown): p is { auth: { key: string } } {\n  return typeof (p as any)?.auth?.key === 'string' && (p as any).auth.key.length > 0\n}","tryCatchPattern":"try { await uppy.upload() }\ncatch (err) { if (/auth\\.key.*required/.test(err.message)) await injectSignedParamsViaGetAssemblyOptions() }","preventionTips":["Serve signed params (key+expires+signature) from your backend via getAssemblyOptions","Log/verify env vars that hold the API key","Check hasAuthKey(params) in a config test"],"tags":["transloadit","auth","api-key","config"],"backgroundTag":"missing-api-key","analyzedSha":"5d4dedd02a1ac0ae022c75c54aca76558f88e256","analyzedAt":"2026-08-28T12:18:41.267Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}