{"record":{"id":"03c5fb14dafdf5bf","repo":"facebook/relay","slug":"this-version-of-act-requires-a-special-mock-buil","errorCode":null,"errorMessage":"This version of `act` requires a special mock build of Scheduler.","messagePattern":"This version of `act` requires a special mock build of Scheduler\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react-relay/jest-react/internalAct.js","lineNumber":41,"sourceCode":"\nconst enqueueTask = require('./enqueueTask');\nconst Scheduler = require('scheduler/unstable_mock');\n\n// The subset of a Promise that React APIs rely on. This resolves a value.\n// This doesn't require a return value neither from the handler nor the\n// then function.\ninterface Thenable<out R> {\n  then<U>(\n    onFulfill: (value: R) => void | Thenable<U> | U,\n    onReject: (error: unknown) => void | Thenable<U> | U,\n  ): void | Thenable<U>;\n}\n\nlet actingUpdatesScopeDepth = 0;\n\nfunction act<T>(scope: () => Thenable<T> | T): Thenable<T> {\n  if (Scheduler.unstable_flushAllWithoutAsserting === undefined) {\n    throw Error(\n      'This version of `act` requires a special mock build of Scheduler.',\n    );\n  }\n  if (setTimeout._isMockFunction !== true) {\n    throw Error(\n      \"This version of `act` requires Jest's timer mocks \" +\n        '(i.e. jest.useFakeTimers).',\n    );\n  }\n\n  const previousIsActEnvironment = global.IS_REACT_ACT_ENVIRONMENT;\n  const previousActingUpdatesScopeDepth = actingUpdatesScopeDepth;\n  actingUpdatesScopeDepth++;\n  if (__DEV__ && actingUpdatesScopeDepth === 1) {\n    // Because this is not the \"real\" `act`, we set this to `false` so React\n    // knows not to fire `act` warnings.\n    global.IS_REACT_ACT_ENVIRONMENT = false;\n  }","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/facebook/relay/blob/668b1b85e06261aa3b58dabfc51f8b5524a70955/packages/react-relay/jest-react/internalAct.js#L23-L59","documentation":"Relay's internal act() (used by RelayTestingEnvironment and relay-test-utils) drives React updates synchronously and relies on the mock Scheduler build exposing unstable_flushAllWithoutAsserting. When the real (non-mock) Scheduler is bundled in tests, that function is undefined and act() refuses to run. This is a test-environment configuration error, not a production issue.","triggerScenarios":"Calling testRender/commitUpdate or any RelayTestingEnvironment API that invokes internal act() in a Jest project where jest-react's required mock Scheduler isn't resolved — e.g. missing jest scheduler mock mapping, or importing production react-reconciler/scheduler into the test bundle.","commonSituations":"Upgrading React/Relay without updating the scheduler moduleNameMapper in jest.config, using a monorepo where scheduler resolves to the npm build instead of the mock, or running relay-test-utils with React 18+ where the mock build contract changed.","solutions":["Add/restore the Jest moduleNameMapper that maps 'scheduler' (and scheduler/unstable_mock) to the mock build expected by jest-react","Pin compatible versions of react, relay, and jest-react; check relay's own jest config for the required mappings","If using React's global IS_REACT_ACT_ENVIRONMENT, prefer React.act/test-utils over Relay's internal act for your React version","Clear node_modules and reinstall if duplicated scheduler copies are resolving in the bundle"],"exampleFix":"// before (jest.config.js): no scheduler mapping\nmoduleNameMapper: {}\n// after\nmoduleNameMapper: {\n  '^scheduler$': '<rootDir>/node_modules/scheduler/unstable_mock.js',\n}","handlingStrategy":"try-catch","validationCode":"// before using relay test APIs\nif (require('scheduler').unstable_flushAllWithoutAsserting === undefined) {\n  throw new Error('Map scheduler to the mock build in jest config before using RelayTestingEnvironment');\n}","typeGuard":null,"tryCatchPattern":"try {\n  testRender(env, <Component />);\n} catch (e) {\n  if (String(e.message).includes('special mock build of Scheduler')) {\n    throw new Error('Jest config missing scheduler mock moduleNameMapper');\n  }\n  throw e;\n}","preventionTips":["Keep jest moduleNameMapper for scheduler aligned with relay's own jest config","Pin compatible react/relay/jest-react versions","Re-verify scheduler mapping after upgrading React"],"tags":["relay","testing","jest","scheduler","act"],"backgroundTag":"act-mock-scheduler-missing","analyzedSha":"668b1b85e06261aa3b58dabfc51f8b5524a70955","analyzedAt":"2026-09-02T19:57:20.783Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}