transloadit/uppy · error · ValidationError

unsupported protocol specified

Error message

unsupported protocol specified

What it means

The optional protocol option must be one of the PROTOCOLS enum values (e.g. 'tus', 's3-multipart', 'xhr-upload' style identifiers). Any other non-falsy value throws a ValidationError.

Source

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

    throw new ValidationError('fieldname must be a string')
  }

  // validate metadata (optional)
  if (options.metadata != null && typeof options.metadata !== 'object') {
    throw new ValidationError('metadata must be an object')
  }

  // validate headers (optional)
  if (options.headers != null && typeof options.headers !== 'object') {
    throw new ValidationError('headers must be an object')
  }

  // validate protocol (optional)
  if (
    options.protocol &&
    !Object.values(PROTOCOLS).includes(options.protocol)
  ) {
    throw new ValidationError('unsupported protocol specified')
  }

  // s3 uploads don't require upload destination
  // validation, because the destination is determined
  // by the server's s3 config
  if (options.protocol !== PROTOCOLS.s3Multipart) {
    if (!options.endpoint && !options.uploadUrl) {
      throw new ValidationError('no destination specified')
    }

    const validateUrl = (url: string | undefined): void => {
      if (url == null) return
      const validatorOpts = { require_protocol: true, require_tld: false }
      if (!validator.isURL(url, validatorOpts)) {
        throw new ValidationError('invalid destination url')
      }

      const allowedUrls = options.companionOptions.uploadUrls

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Import PROTOCOLS from the Uploader module and use PROTOCOLS.s3Multipart etc.
2. Match the exact enum string (e.g. 's3-multipart' with correct spelling/hyphenation)
3. Omit protocol when the default applies

Example fix

// before
new Uploader({ protocol: 's3multipart', ... })

// after
import { PROTOCOLS } from '../server/Uploader.js'
new Uploader({ protocol: PROTOCOLS.s3Multipart, ... })

import { PROTOCOLS } from '@uppy/companion/src/server/Uploader.js'
if (protocol && !Object.values(PROTOCOLS).includes(protocol)) throw new Error('bad protocol')

const isProtocol = (p: unknown, PROTOCOLS: Record<string, string>) => typeof p === 'string' && Object.values(PROTOCOLS).includes(p)

null

When it happens

Trigger: new Uploader({ protocol: 'ftp' }) or a typo like 's3multipart' (missing the exact enum value) — anything not in Object.values(PROTOCOLS).

Common situations: Custom integrations guessing protocol strings instead of importing PROTOCOLS; version changes renaming enum values; case mismatches.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unsupported HTTP METHOD specified
• maxFileSize exceeded
• fieldname must be a string
• metadata must be an object
• headers must be an object

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