vitest-dev/vitest · error · TypeError

[vitest] Mocks require an id string.

Error message

[vitest] Mocks require an id string.

What it means

The positional register overload requires `id` — the unique internal mock identifier — to be a string, since the registry maintains a secondary index (`registryById`) keyed by `id`. A non-string `id` would silently corrupt lookups.

Source

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

      }
      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)
      this.add(mock)
      return mock
    }
    else if (type === 'redirect') {

View on GitHub (pinned to d568f8ce37)

Solutions

1. Provide a unique string id (commonly the resolved specifier or a generated UUID).
2. Check argument order: `(type, raw, id, url, factoryOrRedirect)`.
3. If ids are generated, ensure the generator returns a string.

Example fix

// before
registry.register('automock', raw, 42, url)

// after
registry.register('automock', raw, '/abs/mod', url)

function registerWithId(registry: any, type: string, raw: string, id: unknown, url: string, extra?: unknown) {
  if (typeof id !== 'string' || id.length === 0) {
    throw new TypeError(`register('${type}'): 'id' must be a non-empty string, got ${typeof id}`)
  }
  registry.register(type, raw, id, url, extra)
}

When it happens

Trigger: Calling `registry.register('automock', raw, undefined, url)` or passing a number/object as the id.

Common situations: Generating ids programmatically and forgetting to stringify; misordered arguments; refactor that lost the id.

Related errors

• Unknown mock type: ${(event as any).type}
• [vitest] Mocks require a raw string.
• [vitest] Mocks require a url 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/6f53ba28ed017703.json. Report an issue: GitHub.