transloadit/uppy · error · Error

Unknown multipart upload error

Error message

Unknown multipart upload error

What it means

Fallback error inside the multipart upload try/catch: if the got request failed and the error/response could not be classified (no response body or status message available), Companion throws 'Unknown multipart upload error' with the original error attached as `cause` for diagnostics.

Source

Thrown at packages/@uppy/companion/src/server/Uploader.ts:880

      const errObj = isRecord(err) ? err : null
      const response =
        errObj && isRecord(errObj['response']) ? errObj['response'] : null
      const statusCode =
        response && typeof response['statusCode'] === 'number'
          ? response['statusCode']
          : undefined

      if (statusCode != null) {
        const statusMessage =
          typeof errObj?.['statusMessage'] === 'string'
            ? errObj['statusMessage']
            : 'Request failed'
        throw Object.assign(new Error(statusMessage), {
          extraData: getRespObj(response as unknown as Response<string>),
        })
      }

      throw new Error('Unknown multipart upload error', { cause: err })
    }
  }

  /**
   * Upload the file to S3 using a Multipart upload.
   */
  async #uploadS3Multipart(
    stream: NodeReadableStream,
    req: Request,
  ): Promise<UploadResult> {
    if (!this.options.s3) {
      throw new Error(
        'The S3 client is not configured on this companion instance.',
      )
    }

    const filename = this.uploadFileName
    const s3Options = this.options.s3

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Inspect err.cause on the caught error to find the underlying network/HTTP failure
2. Verify the destination endpoint is reachable from the Companion server (DNS, TLS, firewall)
3. Fix or harden the receiving endpoint based on what cause reveals, then retry

Example fix

// before
catch (err) { console.log(err.message) } // 'Unknown multipart upload error'

// after
catch (err) { console.log(err.message, err.cause) } // reveals e.g. ECONNREFUSED, then fix endpoint/firewall

try { await uploader.upload() } catch (err) {
  if (err.message === 'Unknown multipart upload error') {
    console.error('cause:', err.cause)
    throw err.cause ?? err // surface the real network/HTTP failure
  }
  throw err
}

When it happens

Trigger: got throws a non-HTTP error (DNS failure, socket hang-up, TLS error) or a response with no usable status/body, so the handler cannot build a specific statusMessage and falls through to the generic throw.

Common situations: Destination endpoint unreachable, certificate errors, connection resets, or unexpected response shapes from a custom upload receiver.

Related errors

• uploaded only ${bytesUploaded} of ${this.size} with status:
• unsupported HTTP METHOD specified
• maxFileSize exceeded
• fieldname must be a string
• metadata must be an object

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