transloadit/uppy · critical · TypeError

[s3mini] uploadId must be a non-empty string

Error message

[s3mini] uploadId must be a non-empty string

What it means

Preauth requires a preAuthSecret option on the Companion server, used by tokenService.generateEncryptedToken to encrypt the pre-auth token. If preAuthSecret is null/undefined, Companion returns 500 because it cannot securely mint the token.

Source

Thrown at packages/@uppy/aws-s3/src/s3-client/CompanionS3.ts:160

    })

    const etag = U.sanitizeETag(xhr.getResponseHeader('etag'))
    if (etag == null) {
      throw new Error(
        `${C.ERROR_PREFIX}Missing ETag in uploadPart response headers`,
      )
    }

    return { etag }
  }

  public override async listParts({
    uploadId,
    key,
    signal,
  }: IT.ListPartsParams): Promise<IT.UploadPart[]> {
    if (!uploadId) {
      throw new TypeError(C.ERROR_UPLOAD_ID_REQUIRED)
    }

    const response = await this._fetch(
      `/multipart/${encodeURIComponent(uploadId)}?${new URLSearchParams({ key })}`,
      {
        method: 'GET',
        signal,
      },
    )

    const parts: { PartNumber: string; ETag: string }[] = await response.json()

    return parts.map((p) => ({
      partNumber: parseInt(String(p.PartNumber), 10),
      etag: String(p.ETag),
    }))
  }

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Set the preAuthSecret Companion option or the COMPANION_PREAUTH_SECRET environment variable to a strong random secret
2. Restart Companion after adding the secret
3. Verify the secret is present in the environment of the actual running process (not just the shell)

Example fix

// before
companion({ providerOptions: { url: { credentialsURL: '...' } } })
// after
companion({
  preAuthSecret: process.env.COMPANION_PREAUTH_SECRET,
  providerOptions: { url: { credentialsURL: '...' } },
})

if (!process.env.COMPANION_PREAUTH_SECRET) {
  throw new Error('COMPANION_PREAUTH_SECRET must be set to use preauth')
}

When it happens

Trigger: Running Companion with a provider credentialsURL configured but no preAuthSecret option (or env var) set, then hitting the preauth endpoint.

Common situations: Missing COMPANION_PREAUTH_SECRET environment variable in deployment; secret removed during config refactor; new deployment template that omits the secret.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• File data is missing for file ${options.file.id}
• Missing S3 object key for completing multipart upload
• [s3mini] fileType must be a string
• No uploadId returned
• No key returned

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