vitest-dev/vitest · error · TypeError

[vitest] Mocks require a url string.

Error message

[vitest] Mocks require a url string.

What it means

The positional register overload requires `url` — the resolved absolute file URL of the mocked module (e.g. `file:///abs/path/mod.js`) — to be a string. The registry indexes mocks by `url`, so a non-string value cannot be stored.

Source

Thrown at packages/mocker/src/registry.ts:99

      else if (event.type === 'redirect') {
        const module = RedirectedModule.fromJSON(event)
        this.add(module)
        return module
      }
      else if (event.type === 'manual') {
        throw new Error(`Cannot set serialized manual mock. Define a factory function manually with \`ManualMockedModule.fromJSON()\`.`)
      }
      else {
        throw new Error(`Unknown mock type: ${(event as any).type}`)
      }
    }

    if (typeof raw !== 'string') {
      throw new TypeError('[vitest] Mocks require a raw string.')
    }

    if (typeof url !== 'string') {
      throw new TypeError('[vitest] Mocks require a url string.')
    }

    if (typeof id !== 'string') {
      throw new TypeError('[vitest] Mocks require an id string.')
    }

    if (type === 'manual') {
      if (typeof factoryOrRedirect !== 'function') {
        throw new TypeError('[vitest] Manual mocks require a factory function.')
      }
      const mock = new ManualMockedModule(raw, id, url, factoryOrRedirect)
      this.add(mock)
      return mock
    }
    else if (type === 'automock' || type === 'autospy') {
      const mock = type === 'automock'
        ? new AutomockedModule(raw, id, url)
        : new AutospiedModule(raw, id, url)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass a string URL (call `.href` or `String(url)` if you hold a `URL` object).
2. Confirm argument order: `(type, raw, id, url, factoryOrRedirect)`.
3. Resolve the specifier to a file URL before calling register.

Example fix

// before
registry.register('automock', raw, id, new URL('file:///x'))

// after
registry.register('automock', raw, id, 'file:///abs/path/mod.js')

function toUrlString(url: unknown): string {
  if (typeof url === 'string') return url
  if (url instanceof URL) return url.href
  throw new TypeError(`register(): 'url' must be a string or URL, got ${typeof url}`)
}

registry.register(type, raw, id, toUrlString(url), extra)

When it happens

Trigger: Calling `registry.register('automock', raw, id, undefined)` or passing a non-string `url`, e.g. a URL object.

Common situations: Passing a `URL` instance instead of `.toString()`/`.href`; wrappers that resolve paths asynchronously and forward `undefined`; misordered args.

Related errors

• Unknown mock type: ${(event as any).type}
• [vitest] Mocks require a raw string.
• [vitest] Mocks require an id string.
• [vitest] Manual mocks require a factory function.
• [vitest] Redirect mocks require a redirect string.

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