transloadit/uppy · critical · Error

Companion hostname is required, please consult…

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.

Solutions

Provide companionUrl pointing at your running Companion instance
Deploy Companion (yarn start:companion in dev) or use a hosted Companion endpoint
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 })

Defensive patterns

Strategy: validation

Validate before calling

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 })

Type guard

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

Try / catch

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

Prevention

Gate plugin registration on a validated companionUrl
Use the exact key name companionUrl
Test config in every environment (dev/staging/prod)

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

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

Appendix: 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)