vitest-dev/vitest · error · TypeError

[vitest] Mocks require a raw string.

Error message

[vitest] Mocks require a raw string.

What it means

Thrown as a `TypeError` by `MockerRegistry.register` (multi-argument overload) when the `raw` argument is not a string. `raw` is the original module specifier as written by the user (e.g., the path passed to `vi.mock`); it is used in error messages and as a human-readable identifier, so it must be a string.

Solutions

1. Ensure the original module specifier string is forwarded as the `raw` argument.
2. Double-check argument order against the `register` overloads — the signature is `(type, raw, id, url, factoryOrRedirect)`.
3. Default `raw` to the id or a placeholder string if the original specifier is genuinely unavailable.

Example fix

// before — raw omitted / wrong position
registry.register('automock', undefined, id, url)
// after — forward the specifier
registry.register('automock', rawId, id, url)

// Validate raw is a string before calling register.
function registerSafe(registry: MockerRegistry, type: any, raw: unknown, id: string, url: string, extra?: any) {
  if (typeof raw !== 'string') {
    throw new TypeError('raw must be a string module specifier')
  }
  return registry.register(type, raw, id, url, extra)
}

function isRawSpecifier(value: unknown): value is string {
  return typeof value === 'string'
}

When it happens

Trigger: Calling the multi-arg `register(type, raw, id, url, ...)` with `raw` set to `undefined`, a number, or any non-string — typically an internal caller that forgot to forward the specifier or passed it positionally out of order.

Common situations: Internal mocker code that destructures the RPC result incorrectly; a forked runner that swaps argument order; passing `undefined` when the module has no original specifier.

Related errors

• [vitest] Mocks require a url string.
• [vitest] Mocks require an id string.
• [vitest] Cannot register a mock that is already defined…
• Cannot set serialized manual mock. Define a factory…
• invalid snapshot serializer in

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/59e6771cdcd2b4e1. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)