{"id":"1a1d41586810690d","repo":"jestjs/jest","slug":"failed-to-get-mock-metadata-modulepath-n-nsee","errorCode":null,"errorMessage":"Failed to get mock metadata: ${modulePath}\\n\\nSee: https://jestjs.io/docs/manual-mocks#content","messagePattern":"Failed to get mock metadata: (.+?)\\\\n\\\\nSee: https://jestjs\\.io/docs/manual-mocks#content","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/jest-runtime/src/internals/MockState.ts","lineNumber":452,"sourceCode":"    resolution.resolveCjsStub(from, moduleName) ||\n    resolution.resolveCjs(from, moduleName);\n\n  if (!mockState.hasMockMetadata(modulePath)) {\n    // This allows us to handle circular dependencies while generating an\n    // automock\n    mockState.setMockMetadata(modulePath, moduleMocker.getMetadata({}) || {});\n\n    // In order to avoid it being possible for automocking to potentially\n    // cause side-effects within the module environment, we need to execute\n    // the module in isolation. This could cause issues if the module being\n    // mocked has calls into side-effectful APIs on another module.\n    const moduleExports = registries.withScratchRegistries(() =>\n      requireModule(from, moduleName),\n    );\n\n    const mockMetadata = moduleMocker.getMetadata(moduleExports);\n    if (mockMetadata == null) {\n      throw new Error(\n        `Failed to get mock metadata: ${modulePath}\\n\\n` +\n          'See: https://jestjs.io/docs/manual-mocks#content',\n      );\n    }\n    mockState.setMockMetadata(modulePath, mockMetadata);\n  }\n\n  const moduleMock = moduleMocker.generateFromMetadata<T>(\n    mockState.getMockMetadata(modulePath)! as MockMetadata<T>,\n  );\n  return mockState.notifyMockGenerated(modulePath, moduleMock);\n}\n","sourceCodeStart":434,"sourceCodeEnd":465,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-runtime/src/internals/MockState.ts#L434-L465","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide an explicit factory so Jest does not need to automock: `jest.mock('x', () => ({ ... }))`.","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.","Use `jest.requireActual('x')` to inspect the real exports and decide on a hand-written mock shape.","If automocking must work, refactor the target module so its exports are plain enumerable properties."],"exampleFix":"// before — automock fails because the module exports a primitive\njest.mock('config-value'); // throws 'Failed to get mock metadata'\n\n// after — provide an explicit factory\njest.mock('config-value', () => ({ value: 42 }));","handlingStrategy":"try-catch","validationCode":"// Check that automock metadata can be derived before relying on jest.mock('x')\nconst moduleMocker = new (require('jest-mock').ModuleMocker)(global);\nfunction canAutomock(modulePath) {\n  const exports = require(modulePath);\n  return moduleMocker.getMetadata(exports) != null;\n}","typeGuard":null,"tryCatchPattern":"jest.mock('maybe-automockable');\ntry {\n  require('maybe-automockable');\n} catch (e) {\n  if (e.message.startsWith('Failed to get mock metadata')) {\n    // fall back to an explicit factory\n    jest.mock('maybe-automockable', () => ({ known: 'shape' }));\n  } else {\n    throw e;\n  }\n}","preventionTips":["Provide an explicit factory (`jest.mock(name, () => ({...}))`) for modules with non-standard exports.","Add a manual mock under __mocks__/ for modules that cannot be automocked.","Avoid automocking modules whose exports are primitives, Proxies, or rely on getters."],"tags":["mocking","automock","manual-mocks","introspection"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}