jestjs/jest · error · Error

Failed to get mock metadata: ${modulePath}\n\nSee: https://j

Error message

Failed to get mock metadata: ${modulePath}\n\nSee: https://jestjs.io/docs/manual-mocks#content

What it means

Thrown by generateMock (the automock generator) when `moduleMocker.getMetadata(moduleExports)` returns null after the module was required in a scratch registry. This means Jest successfully loaded the module but could not introspect its exports into mock metadata, so it cannot synthesize an automock. The message points at the manual mocks docs as the workaround.

Source

Thrown at packages/jest-runtime/src/internals/MockState.ts:452

    resolution.resolveCjsStub(from, moduleName) ||
    resolution.resolveCjs(from, moduleName);

  if (!mockState.hasMockMetadata(modulePath)) {
    // This allows us to handle circular dependencies while generating an
    // automock
    mockState.setMockMetadata(modulePath, moduleMocker.getMetadata({}) || {});

    // In order to avoid it being possible for automocking to potentially
    // cause side-effects within the module environment, we need to execute
    // the module in isolation. This could cause issues if the module being
    // mocked has calls into side-effectful APIs on another module.
    const moduleExports = registries.withScratchRegistries(() =>
      requireModule(from, moduleName),
    );

    const mockMetadata = moduleMocker.getMetadata(moduleExports);
    if (mockMetadata == null) {
      throw new Error(
        `Failed to get mock metadata: ${modulePath}\n\n` +
          'See: https://jestjs.io/docs/manual-mocks#content',
      );
    }
    mockState.setMockMetadata(modulePath, mockMetadata);
  }

  const moduleMock = moduleMocker.generateFromMetadata<T>(
    mockState.getMockMetadata(modulePath)! as MockMetadata<T>,
  );
  return mockState.notifyMockGenerated(modulePath, moduleMock);
}

View on GitHub (pinned to f49721c78e)

Solutions

1. Provide an explicit factory so Jest does not need to automock: `jest.mock('x', () => ({ ... }))`.
2. Create a manual mock in `__mocks__/x.js` adjacent to the module (or under rootDir/__mocks__ for node_modules) — see https://jestjs.io/docs/manual-mocks.
3. Use `jest.requireActual('x')` to inspect the real exports and decide on a hand-written mock shape.
4. If automocking must work, refactor the target module so its exports are plain enumerable properties.

Example fix

// before — automock fails because the module exports a primitive
jest.mock('config-value'); // throws 'Failed to get mock metadata'

// after — provide an explicit factory
jest.mock('config-value', () => ({ value: 42 }));

// Check that automock metadata can be derived before relying on jest.mock('x')
const moduleMocker = new (require('jest-mock').ModuleMocker)(global);
function canAutomock(modulePath) {
  const exports = require(modulePath);
  return moduleMocker.getMetadata(exports) != null;
}

jest.mock('maybe-automockable');
try {
  require('maybe-automockable');
} catch (e) {
  if (e.message.startsWith('Failed to get mock metadata')) {
    // fall back to an explicit factory
    jest.mock('maybe-automockable', () => ({ known: 'shape' }));
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling `jest.mock('x')` (automock, no factory) for a CJS module whose exports are not introspectable by `jest-mock`'s metadata walker — e.g. the module exports only primitives wired via getters, a class with non-enumerable methods, a Proxy, or `undefined`. Also triggered when the module throws during scratch-require but in a way that yields a non-introspectable export.

Common situations: Automocking a module that exports a single primitive (`module.exports = 42`) or a function with no own properties; automocking a third-party module whose main export is a Proxy or has Symbol-keyed members; circular dependencies that leave the scratch-require with a partial export.

Related errors

• Attempting to import a mock without a factory
• `unstable_mockModule` must be passed a mock factory

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