vitest-dev/vitest · error · Error
Mock ${id} wasn't registered. This is probably a Vitest erro
Error message
Mock ${id} wasn't registered. This is probably a Vitest error. Please, open a new issue with reproduction. What it means
Thrown by resolveFactoryModule at packages/mocker/src/browser/mocker.ts:32-35 when the registry has no entry for the id, or the entry is not of type 'manual'. This method resolves a manually-mocked module (one defined via vi.mock with a factory) and expects a ManualMockedModule to already be registered during prepare().
Source
Thrown at packages/mocker/src/browser/mocker.ts:34
constructor(
private interceptor: ModuleMockerInterceptor,
private rpc: ModuleMockerRPC,
private createMockInstance: CreateMockInstanceProcedure,
private config: ModuleMockerConfig,
) {}
public async prepare(): Promise<void> {
if (!this.queue.size) {
return
}
await Promise.all([...this.queue.values()])
}
public async resolveFactoryModule(id: string): Promise<Record<string | symbol, any>> {
const mock = this.registry.get(id)
if (!mock || mock.type !== 'manual') {
throw new Error(`Mock ${id} wasn't registered. This is probably a Vitest error. Please, open a new issue with reproduction.`)
}
const result = await mock.resolve()
return result
}
public getFactoryModule(id: string): any {
const mock = this.registry.get(id)
if (!mock || mock.type !== 'manual') {
throw new Error(`Mock ${id} wasn't registered. This is probably a Vitest error. Please, open a new issue with reproduction.`)
}
if (!mock.cache) {
throw new Error(`Mock ${id} wasn't resolved. This is probably a Vitest error. Please, open a new issue with reproduction.`)
}
return mock.cache
}
public async invalidate(): Promise<void> {
const ids = Array.from(this.mockedIds)View on GitHub (pinned to d568f8ce37)
Solutions
- Ensure vi.mock(path, factory) was called for the id and that prepare() awaited before resolution.
- Avoid manually invoking invalidate()/reset() in a way that clears mocks still in use.
- Report with a reproduction as the message flags it as a probable Vitest error.
Defensive patterns
Strategy: try-catch
Try / catch
// Internal registry error; cannot be pre-validated by user code.
// Catch to add context and report.
try {
vi.mock('./x', factory)
} catch (e) {
if (e instanceof Error && /wasn't registered/.test(e.message)) {
console.error('Vitest internal: mock factory module not registered. Report with reproduction.')
}
throw e
} Prevention
- Await prepare() / let Vitest manage mock registration timing.
- Avoid calling mocker.invalidate()/reset() mid-test on mocks still in use.
- Keep @vitest/mocker and vitest versions aligned.
When it happens
Trigger: resolveFactoryModule(id) is called for an id that was never queued via queueMock with a factory, or before prepare() finished registering mocks, or after the registry was cleared/reset.
Common situations: Vitest internal ordering issue where the factory module is requested before queueMock completed; a reset()/invalidate() clearing the registry mid-run; version mismatch causing the registration path to diverge.
Related errors
- Mock ${id} wasn't resolved. This is probably a Vitest error.
- Cannot set serialized manual mock. Define a factory function
- [vitest] Manual mocks require a factory function.
- Cannot find iframe with id ${event.iframeId}
- Cannot spawn child server without a parent dev server.
AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03).
Data as JSON: /data/errors/ab2ee311224bae86.json.
Report an issue: GitHub.