transloadit/uppy · error · TypeError

[s3mini] key must be a non-empty string

Error message

[s3mini] key must be a non-empty string

What it means

A guard in s3mini that requires the object `key` to be a non-empty, non-whitespace string. Every object-level operation (putObject, createMultipartUpload, listParts, abortMultipartUpload, uploadPart validation) calls _checkKey before making a request, because S3 needs a valid object key to build the request path. It throws a TypeError when the key is missing, not a string, or blank.

Source

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

      new URL(candidate)

      // Find the last non-slash character
      let endIndex = candidate.length
      while (endIndex > 0 && candidate[endIndex - 1] === '/') {
        endIndex--
      }
      return endIndex === candidate.length
        ? candidate
        : candidate.substring(0, endIndex)
    } catch {
      const msg = `${C.ERROR_ENDPOINT_FORMAT} But provided: "${raw}"`
      throw new TypeError(msg)
    }
  }

  private _checkKey(key: string): void {
    if (typeof key !== 'string' || key.trim().length === 0) {
      throw new TypeError(C.ERROR_KEY_REQUIRED)
    }
  }

  private _validateUploadPartParams(
    key: string,
    uploadId: string,
    partNumber: number,
  ): void {
    this._checkKey(key)
    if (typeof uploadId !== 'string' || uploadId.trim().length === 0) {
      throw new TypeError(C.ERROR_UPLOAD_ID_REQUIRED)
    }
    if (!Number.isInteger(partNumber) || partNumber <= 0) {
      throw new TypeError(
        `${C.ERROR_PREFIX}partNumber must be a positive integer`,
      )
    }
  }

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Ensure the key passed to the S3 call is a non-empty string, e.g. derive it deterministically: `key = \`${folder}/${file.name}\`` and fall back to a generated name if `file.name` is empty.
2. If the key comes from user input or metadata, validate/trim it before calling the API.
3. Check that you're not passing the key under a different option name (e.g. `path`, `name`) than the API expects.

Example fix

// before
await s3.createMultipartUpload({ key: file.meta.key }) // undefined
// after
const key = file.meta.key ?? `uploads/${crypto.randomUUID()}-${file.name}`
await s3.createMultipartUpload({ key })

const key = typeof file.key === 'string' && file.key.trim() ? file.key : `uploads/${crypto.randomUUID()}-${file.name}`

const isValidKey = (k: unknown): k is string =>
  typeof k === 'string' && k.trim().length > 0

try { await s3.putObject({ key, body }) } catch (e) { if (e instanceof TypeError && /non-empty string/.test(e.message)) {/* regenerate key and retry */} else throw e }

When it happens

Trigger: Calling putObject({ key: '' }) or createMultipartUpload({ key: undefined }); passing a key of only spaces; key computed from a filename that is undefined (e.g. `file.meta.key` that was never set); passing a Buffer or object as key.

Common situations: Uppy/AWS S3 uploader generating the key from file metadata where the field is absent; renaming/refactoring key-generation code so it returns undefined; user uploads where the filename is empty and the key template produces a blank string.

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

• [s3mini] uploadId must be a non-empty string
• [s3mini] partNumber must be a positive integer
• [s3mini] fileType must be a string
• [s3mini] Failed to create multipart upload: ${JSON.stringify
• [s3mini] Missing ETag in uploadPart response headers

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