hcengineering/platform · error

Failed to initialize multipart upload

Error message

Failed to initialize multipart upload

What it means

multipartUploadCreate sends POST to the multipart upload base URL to initialize a session and expects a JSON body {uuid, uploadId}. If the fetch returns a non-ok status, it throws 'Failed to initialize multipart upload'. Because the status/body are discarded, auth errors, wrong endpoints and server failures all look identical.

Source

Thrown at foundations/core/packages/storage-client/src/upload.ts:184

function throwIfAborted (signal?: AbortSignal): void {
  if (signal?.aborted === true) {
    throw new Error('Upload aborted')
  }
}

async function multipartUploadCreate (
  baseUrl: string,
  headers: Record<string, string>,
  signal?: AbortSignal
): Promise<{ uuid: string, uploadId: string }> {
  const response = await fetch(baseUrl, {
    signal,
    method: 'POST',
    headers
  })

  if (!response.ok) {
    throw new Error('Failed to initialize multipart upload')
  }

  const { uuid, uploadId } = await response.json()
  return { uuid, uploadId }
}

async function multipartUploadComplete (
  baseUrl: string,
  headers: Record<string, string>,
  uploadId: string,
  parts: Array<{ partNumber: number, etag: string }>,
  signal?: AbortSignal
): Promise<void> {
  const url = new URL(concatLink(baseUrl, '/complete'))
  url.searchParams.set('uploadId', uploadId)

  const response = await fetch(url, {
    signal,

View on GitHub (pinned to 63e28dc964)

Solutions

1. Log response.status for the init request (patch or wrap uploadMultipart) to distinguish auth vs routing vs server error.
2. Verify the baseUrl is the full multipart endpoint and that the deployed storage service supports multipart uploads.
3. Refresh the Bearer token; 401 on init is the most common cause.
4. Retry with backoff on 5xx; if the service lacks multipart support, downgrade by uploading files in chunks below the 10MB single-shot threshold.

Example fix

// before: baseUrl may be missing the multipart path
await uploadFile(token, ws, uuid, bigFile) // POST to wrong URL -> 404

// after: ensure correct multipart URL
const url = concatLink(baseUrl, `/upload/multipart/${encodeURIComponent(ws)}/${encodeURIComponent(uuid)}`)
await uploadMultipart({ url, headers: { Authorization: `Bearer ${token}` }, body: bigFile })

// pre-flight: token present and endpoint reachable
if (token === undefined) throw new Error('Missing token for multipart upload')
const probe = await fetch(baseUrl, { method: 'OPTIONS' })
if (!probe.ok) console.warn('multipart endpoint not reachable:', baseUrl)

null

let lastErr: unknown
for (let attempt = 0; attempt < 3; attempt++) {
  try { await uploadMultipart({ url, headers, body: file }, { signal }); return }
  catch (err) {
    if (err instanceof Error && err.message === 'Failed to initialize multipart upload') {
      lastErr = err; await new Promise(r => setTimeout(r, 2 ** attempt * 500)); continue
    }
    throw err
  }
}
throw lastErr

When it happens

Trigger: uploadMultipart starts (files >10MB trigger it via uploadFile) and the POST to baseUrl fails: 401/403 (bad Bearer token), 404 (baseUrl doesn't implement multipart endpoints), 405 (wrong HTTP method routing), or 5xx from the storage service.

Common situations: Storage service without multipart support (older deployment) receiving a large-file upload; baseUrl missing the /upload/multipart/<workspace>/<uuid> suffix; expired token during long sessions; reverse proxy rejecting POST without Content-Type expectations; hitting a regional endpoint that doesn't serve the workspace.

Related errors

• Failed to complete multipart upload
• Failed to parse response for part ${partNumber}
• Failed to reject multipart upload
• missing files
• response.statusText

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/86e5c9b4acc464ab. Report an issue: GitHub.