jestjs/jest · error · TypeError

`unstable_mockModule` must be passed a mock factory

Error message

`unstable_mockModule` must be passed a mock factory

What it means

TypeError thrown by the `jest.unstable_mockModule` implementation when the second argument (the mock factory) is not a function. ESM module mocking requires an explicit factory because automocking is not supported for ESM, so a non-function factory is rejected up front.

Source

Thrown at packages/jest-runtime/src/internals/JestGlobals.ts:209

    ) => {
      this.mockState.addOnGenerateMock(cb);
      return jestObject;
    };
    const setMockFactory = (
      moduleName: string,
      mockFactory: () => unknown,
      options?: {virtual?: boolean},
    ) => {
      this.setMockBridge(from, moduleName, mockFactory, options);
      return jestObject;
    };
    const mockModule: Jest['unstable_mockModule'] = (
      moduleName,
      mockFactory,
      options,
    ) => {
      if (typeof mockFactory !== 'function') {
        throw new TypeError(
          '`unstable_mockModule` must be passed a mock factory',
        );
      }

      this.setModuleMockBridge(from, moduleName, mockFactory, options);
      return jestObject;
    };
    const clearAllMocks = () => {
      this.clearAllMocksBridge();
      return jestObject;
    };
    const resetAllMocks = () => {
      this.resetAllMocksBridge();
      return jestObject;
    };
    const restoreAllMocks = () => {
      this.restoreAllMocksBridge();
      return jestObject;

View on GitHub (pinned to f49721c78e)

Solutions

Pass a function as the second argument: `jest.unstable_mockModule('x', () => ({ ... }))`.
Double-check that the factory is an arrow or normal function, not a plain object.
If using TypeScript, the type signature should already flag this; ensure `@types/jest`/`@jest/globals` is up to date.

Example fix

// before
jest.unstable_mockModule('my-module', { doThing: () => 'x' });

// after
jest.unstable_mockModule('my-module', () => ({ doThing: () => 'x' }));

Defensive patterns

Strategy: type-guard

Validate before calling

function mockModule(name, factory) {
  if (typeof factory !== 'function') {
    throw new TypeError('unstable_mockModule requires a factory function');
  }
  jest.unstable_mockModule(name, factory);
}

Type guard

function isMockFactory(f: unknown): f is () => Record<string, unknown> {
  return typeof f === 'function';
}

Prevention

Always pass an arrow/normal function as the second argument, not a plain object.
Enable @jest/globals types so TypeScript flags a missing factory at compile time.
Wrap unstable_mockModule in a project-local helper that validates the factory type.

When it happens

Trigger: Calling `jest.unstable_mockModule('x', factory)` where `factory` is undefined, null, an object, or any non-function value. Common when the caller forgets the second argument or passes the mock object directly instead of a function returning it.

Common situations: Forgetting the factory argument entirely; passing `{ doThing: fn }` (the exports object) instead of `() => ({ doThing: fn })` (a factory returning it); migrating from `jest.mock('x', () => ({...}))` and dropping the arrow by mistake.

Related errors

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/b06fb94342968dff.json. Report an issue: GitHub.