transloadit/uppy · error · TypeError

ERROR_UPLOAD_ID_REQUIRED

Error message

ERROR_UPLOAD_ID_REQUIRED

What it means

listParts() requires an uploadId because it lists the already-uploaded parts of a specific multipart upload. Passing a falsy uploadId throws a TypeError immediately before any network call.

Source

Thrown at packages/@uppy/aws-s3/src/s3-client/S3mini.ts:385

          xhr.status,
          serviceCode,
          xhr.responseText,
        )
      }

      throw err
    }
  }

  /** Lists uploaded parts for a multipart upload. */
  public override async listParts({
    uploadId,
    key,
    signal,
  }: IT.ListPartsParams): Promise<IT.UploadPart[]> {
    this._checkKey(key)
    if (!uploadId) {
      throw new TypeError(C.ERROR_UPLOAD_ID_REQUIRED)
    }
    const { xhr } = await this.request({
      request: { method: 'GET', key, uploadId },
      signal,
    })

    const parsed = U.parseXml(xhr.responseText) as Record<string, unknown>
    const result = (parsed.listPartsResult ||
      parsed.ListPartsResult ||
      parsed) as Record<string, unknown>

    if (result && typeof result === 'object') {
      const parts = result.Part || result.part || []
      const partsArray = Array.isArray(parts) ? parts : [parts]

      return partsArray
        .filter(
          (p): p is Record<string, unknown> =>

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Ensure createMultipartUpload() has resolved and its uploadId is passed through
2. Persist { key, uploadId } together and pass both to listParts
3. Guard calls with a falsy check when uploadId may be absent

Example fix

// before
await s3Mini.listParts({ key, uploadId: state.uploadId })

// after
if (!state.uploadId) throw new Error('no active multipart upload')
await s3Mini.listParts({ key, uploadId: state.uploadId })

if (!uploadId) throw new TypeError('uploadId is required to list parts')

const hasUploadId = (s: { uploadId?: string }): s is { uploadId: string } => Boolean(s.uploadId)

try { await listParts({ key, uploadId }) } catch (e) { if (e instanceof TypeError) handleMissingUploadId(); else throw e }

When it happens

Trigger: Calling s3Mini.listParts({ key, uploadId: undefined }) or with an empty string, e.g. when the uploadId from createMultipartUpload was lost or never awaited.

Common situations: Race where abort/complete runs before createMultipartUpload resolves; storing upload state incompletely; refactoring that drops the uploadId field.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• S3 returned ${xhr.status}${serviceCode ? ` – ${serviceCode}`
• ${C.ERROR_PREFIX}CompleteMultipartUpload response missing Lo
• ${C.ERROR_PREFIX}Failed to complete multipart upload: ${JSON
• ${C.ERROR_PREFIX}Failed to abort multipart upload: ${String(
• region must be a string

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