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 Url plugin (the 'Import from link' acquirer) fetches remote URLs through Companion, so a companionUrl is mandatory. The constructor throws when the resolved hostname is falsy before the internal RequestClient is created.

Source

Thrown at packages/@uppy/url/src/Url.tsx:118

  canHandleRootDrop!: typeof canHandleRootDrop

  constructor(uppy: Uppy<M, B>, opts: UrlOptions) {
    super(uppy, opts)
    this.id = this.opts.id || 'Url'
    this.type = 'acquirer'
    this.icon = () => <UrlIcon />

    // Set default options and locale
    this.defaultLocale = locale

    this.i18nInit()
    this.title = this.i18n('pluginNameUrl')

    this.hostname = this.opts.companionUrl

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

    this.client = new RequestClient(uppy, {
      companionUrl: this.opts.companionUrl,
      companionHeaders: this.opts.companionHeaders,
      companionCookiesRule: this.opts.companionCookiesRule,
    })

    this.uppy.registerRequestClient(Url.requestClientId, this.client)
  }

  private getMeta = (url: string): Promise<MetaResponse> => {
    return this.client.post<MetaResponse>('url/meta', { url })
  }

  private addFile = async (

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Provide companionUrl pointing at your running Companion instance
2. Deploy Companion (yarn start:companion in dev) or use a hosted Companion endpoint
3. Double-check the exact option key is companionUrl and the value is non-empty at runtime

Example fix

// before
uppy.use(Url, { companionUrl: process.env.COMPANION_URL })

// after
const companionUrl = process.env.COMPANION_URL
if (companionUrl) uppy.use(Url, { companionUrl })

const companionUrl = process.env.COMPANION_URL
if (!companionUrl) throw new Error('COMPANION_URL must be set to use the Url plugin')
uppy.use(Url, { companionUrl })

const hasCompanionUrl = (opts: { companionUrl?: string }): opts is { companionUrl: string } => typeof opts.companionUrl === 'string' && opts.companionUrl.length > 0

try { uppy.use(Url, { companionUrl }) } catch (e) { if (e.message.includes('Companion hostname')) console.warn('Url plugin skipped') }

When it happens

Trigger: new Url(uppy, { companionUrl: '' }) or omitting companionUrl entirely; also companionUrl set to undefined via conditional spread that evaluates falsy.

Common situations: Same-family config mistake as other provider plugins: examples omitting the option, wrong option name (companion vs companionUrl), empty environment variable in CI/staging, or assuming the plugin fetches URLs client-side without a server.

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/88e4880ed46b01dd. Report an issue: GitHub.