vitest-dev/vitest · error · Error

Inspector host cannot be a URL. Use "host:port" instead of "

Error message

Inspector host cannot be a URL. Use "host:port" instead of "${inspect}"

What it means

Thrown by parseInspector() when the `--inspect` (or api/server inspect) value looks like a URL (matches /https?:\//). Node's inspector expects a `host:port` string, not a URL with a scheme; passing a URL would fail silently or connect to the wrong target, so Vitest rejects it up front.

Source

Thrown at packages/vitest/src/node/config/resolveConfig.ts:77

export function findConfigFile(root: string): string | undefined {
  for (const configFile of configFiles) {
    const configPath = resolve(root, configFile)
    if (existsSync(configPath)) {
      return configPath
    }
  }
}

function parseInspector(inspect: string | undefined | boolean | number) {
  if (typeof inspect === 'boolean' || inspect === undefined) {
    return {}
  }
  if (typeof inspect === 'number') {
    return { port: inspect }
  }

  if (/https?:\//.test(inspect)) {
    throw new Error(
      `Inspector host cannot be a URL. Use "host:port" instead of "${inspect}"`,
    )
  }

  const [host, port] = inspect.split(':')
  if (!port) {
    return { host }
  }
  return { host, port: Number(port) || defaultInspectPort }
}

export function resolveApiServerConfig(
  config: UserConfig,
  defaultPort: number,
  logger: Logger,
): ApiConfig {
  const isBrowserEnabled = !!config.browser?.enabled

View on GitHub (pinned to d568f8ce37)

Solutions

Use host:port form without a scheme: `--inspect=localhost:9229` or `--inspect=127.0.0.1:9229`.
For just a port, pass a number: `--inspect=9229`.
If you need a ws:// inspector URL for a custom client, configure it at the transport layer, not via --inspect.

Example fix

# before
vitest --inspect=http://localhost:9229
# after
vitest --inspect=localhost:9229

Defensive patterns

Strategy: validation

Validate before calling

function parseInspect(v: string): string {
  if (/https?:\/\//.test(v)) {
    throw new Error('inspect must be host:port, not a URL')
  }
  return v
}

Type guard

function isHostPort(v: unknown): v is string {
  return typeof v === 'string' && !/https?:\/\//.test(v)
}

Prevention

Pass --inspect as host:port (e.g. localhost:9229) or a bare port number.
Never paste a chrome://inspect or ws:// URL into --inspect.
Validate inspector config strings before launching Vitest.

When it happens

Trigger: Passing `--inspect=http://localhost:9229` or `--inspect=https://host:9229` on the CLI or in config. The regex /https?:\// matches and the error fires, telling the user to drop the scheme.

Common situations: Copy-pasting a DevTools `chrome://inspect` URL or a ws:// debugger URL into --inspect; assuming --inspect takes a full inspector-protocol URL; config migrated from a browser-DevTools setup.

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/baa1db3d19f83413.json. Report an issue: GitHub.