transloadit/uppy · critical · Error

Companion hostname is required, please consult https://uppy.

Error message

Companion hostname is required, please consult https://uppy.io/docs/companion

What it means

The Unsplash provider plugin requires a Companion server URL because all Unsplash API traffic is proxied through Companion. The constructor throws immediately if opts.companionUrl is falsy, pointing at the Companion docs.

Source

Thrown at packages/@uppy/unsplash/src/Unsplash.tsx:73

    this.title = this.i18n('pluginNameUnsplash')

    this.icon = () => (
      <svg
        className="uppy-DashboardTab-iconUnsplash"
        viewBox="0 0 32 32"
        height="32"
        width="32"
        aria-hidden="true"
      >
        <g fill="currentcolor">
          <path d="M46.575 10.883v-9h12v9zm12 5h10v18h-32v-18h10v9h12z" />
          <path d="M13 12.5V8h6v4.5zm6 2.5h5v9H8v-9h5v4.5h6z" />
        </g>
      </svg>
    )

    if (!this.opts.companionUrl) {
      throw new Error(
        'Companion hostname is required, please consult https://uppy.io/docs/companion',
      )
    }

    this.hostname = this.opts.companionUrl

    this.opts.companionAllowedHosts = getAllowedHosts(
      this.opts.companionAllowedHosts,
      this.opts.companionUrl,
    )
    this.provider = new SearchProvider(uppy, {
      companionUrl: this.opts.companionUrl,
      companionHeaders: this.opts.companionHeaders,
      companionCookiesRule: this.opts.companionCookiesRule,
      provider: 'unsplash',
      pluginId: this.id,
    })
  }

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Pass a valid companionUrl: new Unsplash(uppy, { companionUrl: 'https://your-companion.example.com' })
2. If self-hosting, deploy Companion and use its URL; if using Transloadit, use the Transloadit Companion URL
3. Verify the env var feeding companionUrl is actually set in the failing environment

Example fix

// before
uppy.use(Unsplash, {})

// after
uppy.use(Unsplash, { companionUrl: 'https://companion.myapp.com' })

const companionUrl = process.env.COMPANION_URL
if (companionUrl) uppy.use(Unsplash, { companionUrl })

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

try { uppy.use(Unsplash, { companionUrl }) } catch (e) { if (e.message.includes('Companion hostname')) console.warn('Unsplash disabled: no Companion') }

When it happens

Trigger: new Unsplash(uppy, {}) or with companionUrl: '' / undefined. Any instantiation without a configured Companion endpoint.

Common situations: Copy-pasting example code that omits companionUrl, forgetting that provider plugins need a server, setting the option under a wrong key (e.g. companion instead of companionUrl), or env-variable-driven config that's empty in some environment.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Companion hostname is required, please consult https://uppy.
• Missing S3 object key for completing multipart upload
• [s3mini] fileType must be a string
• If you want to use '/' as server.path, leave the 'path' vari
• The Provider option "providerOptions.${deprecated}" is no lo

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