vitest-dev/vitest · error · TypeError

[vitest] Mocks require a raw string.

Error message

[vitest] Mocks require a raw string.

What it means

The positional overload `register(type, raw, id, url, factoryOrRedirect)` requires the second argument `raw` — the original module specifier exactly as written in user code (e.g. `'./config'`) — to be a string. Passing `undefined` or a non-string is treated as a programmer error.

Source

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

        const module = AutospiedModule.fromJSON(event)
        this.add(module)
        return module
      }
      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
    }

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass the original specifier string as the second argument.
2. Verify argument order against the overload signature: `(type, raw, id, url, factoryOrRedirect)`.
3. Enable strict TypeScript checks so missing string args are caught at compile time.

Example fix

// before
registry.register('automock', undefined, id, url)

// after
registry.register('automock', './config', id, url)

function registerTyped(registry: any, type: string, raw: unknown, id: string, url: string, extra?: unknown) {
  if (typeof raw !== 'string') {
    throw new TypeError(`register('${type}'): 'raw' must be a string specifier, got ${typeof raw}`)
  }
  registry.register(type, raw, id, url, extra)
}

When it happens

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

Common situations: Programmatic mock construction in wrappers; misordered arguments; refactor that dropped the specifier.

Related errors

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