transloadit/uppy · error · Error

Transloadit: Assembly status is missing `assembly_id`.

Error message

Transloadit: Assembly status is missing `assembly_id`.

What it means

ensureAssemblyId throws when an Assembly status response from Transloadit lacks assembly_id. The plugin first logs a console.warn with the full status payload, then throws — meaning the Transloadit API answered with something unexpected (error payload, rate-limit body, or an API version mismatch) instead of a proper Assembly status.

Source

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

        { 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 {
  for (const value of candidates) {
    if (typeof value === 'string' && value.length > 0) {
      return value
    }
  }
  throw new Error(`Transloadit: Assembly status is missing ${label}.`)
}

export function getAssemblyUrl(
  assembly: Pick<AssemblyResponse, 'assembly_ssl_url' | 'assembly_url'>,

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Look at the console.warn output right before the throw — it contains the actual Transloadit response explaining the failure (e.g. RATE_LIMIT_REACHED, INVALID_TEMPLATE_ID)
2. Verify your Transloadit account status/credits and rate limits
3. Confirm the template_id exists for the auth key used
4. Upgrade @uppy/transloadit (and Companion if involved) to the latest version to match the current Assembly API shape

Example fix

// before
uppy.use(Transloadit, { params: { auth: { key: 'k' }, template_id: 'does-not-exist' } })
await uppy.upload()
// console.warn shows { error: 'INVALID_TEMPLATE_ID' ... } then throws

// after
uppy.use(Transloadit, {
  params: { auth: { key: 'k' }, template_id: 'valid-template-id' },
})

// Before upload, sanity-check the template resolves
const resp = await fetch('https://api2.transloadit.com/templates/my-template-id', {
  headers: { 'Transloadit-Key': key },
})
if (!resp.ok) throw new Error('Template or account problem — inspect response')

function isAssemblyIdError(e: unknown): boolean {
  return e instanceof Error && /missing `assembly_id`/.test(e.message)
}

try { await uppy.upload() }
catch (err) {
  if (isAssemblyIdError(err)) {
    // the console.warn printed just before contains the true cause
    uppy.info('Processing service rejected the request. Check console & account status.', 'error', 5000)
  }
}

When it happens

Trigger: Any Assembly status fetch/create where the JSON body has no assembly_id field: #prepareUpload creating an assembly, restoreAssemblies on boot, or the socket/polling update paths calling ensureAssemblyId. Typical when Transloadit returns an error object ('error': 'RATE_LIMIT_REACHED', invalid template, account suspended) with HTTP 200-level or followed by json without id.

Common situations: Transloadit account out of credits or rate-limited; a template_id that doesn't exist under that auth key; API response shape changed (old @uppy/transloadit against a newer/older backend); signing clock skew producing accepted-but-error bodies.

Related errors

• Transloadit: Assembly status is missing ${label}.
• All files were canceled after assembly was created
• Failed to list folder contents for '${doc.name}' (${doc.id})
• Transloadit: The `params` option is required.
• Transloadit: The `params` option is a malformed JSON string.

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