transloadit/uppy · error · Error

If you want to use '/' as server.path, leave the 'path' vari

Error message

If you want to use '/' as server.path, leave the 'path' variable unset

What it means

Companion historically cannot serve correctly when server.path is '/', so validateConfig rejects it and asks you to leave path unset (which already defaults to root mounting). See uppy issue #4271.

Source

Thrown at packages/@uppy/companion/src/config/companion.ts:110

export function validateConfig(companionOptions: CompanionInitOptions): void {
  const parsedConfig = validateConfigSchema.parse(companionOptions)
  const { filePath } = parsedConfig

  // validate that specified filePath is writeable/readable.
  try {
    fs.accessSync(filePath, fs.constants.R_OK | fs.constants.W_OK)
  } catch {
    throw new Error(
      `No access to "${filePath}". Please ensure the directory exists and with read/write permissions.`,
    )
  }

  const { providerOptions, server, uploadUrls } = companionOptions

  // see https://github.com/transloadit/uppy/issues/4271
  // todo fix the code so we can allow `/`
  if (server.path === '/') {
    throw new Error(
      "If you want to use '/' as server.path, leave the 'path' variable unset",
    )
  }

  if (providerOptions) {
    const deprecatedOptions: Record<string, string> = {
      microsoft: 'providerOptions.onedrive',
      google: 'providerOptions.drive',
      s3: 's3',
    }
    Object.keys(deprecatedOptions).forEach((deprecated) => {
      if (Object.hasOwn(providerOptions, deprecated)) {
        throw new Error(
          `The Provider option "providerOptions.${deprecated}" is no longer supported. Please use the option "${deprecatedOptions[deprecated]}" instead.`,
        )
      }
    })
  }

View on GitHub (pinned to 5d4dedd02a)

Solutions

1. Remove the path option entirely (root is the default)
2. If you need a prefix, use a non-root path like '/companion'

Example fix

// before
server: { path: '/' }

// after
server: {}

if (server.path === '/') delete server.path

null

null

When it happens

Trigger: Setting { server: { path: '/' } } in the Companion options/config file.

Common situations: Trying to explicitly mount Companion at the root path when reverse-proxying; copying configs from tutorials that set path: '/'.

Understand the failure class

Background: "Invalid configuration value" and "Unsupported/Unknown setting value" errors: why libraries reject your config strings, numbers, and types — this error's family across 30 libraries.

Related errors

• uploadUrls is required
• Option corsOrigins is required. To disable security, pass tr
• Missing S3 object key for completing multipart upload
• [s3mini] fileType must be a string
• No access to "${filePath}". Please ensure the directory exis

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