{"id":"8a08a123070fa44e","repo":"jestjs/jest","slug":"jest-advancetimersbytimeasync-is-not-available","errorCode":null,"errorMessage":"`jest.advanceTimersByTimeAsync()` is not available when using legacy fake timers.","messagePattern":"`jest\\.advanceTimersByTimeAsync\\(\\)` is not available when using legacy fake timers\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/jest-runtime/src/internals/JestGlobals.ts","lineNumber":303,"sourceCode":"      this.environment.global[logErrorsBeforeRetrySymbol] =\n        options?.logErrorsBeforeRetry;\n      this.environment.global[waitBeforeRetrySymbol] = options?.waitBeforeRetry;\n      this.environment.global[retryImmediatelySymbol] =\n        options?.retryImmediately;\n\n      return jestObject;\n    };\n\n    const jestObject: Jest = {\n      advanceTimersByTime: msToRun =>\n        _getFakeTimers().advanceTimersByTime(msToRun),\n      advanceTimersByTimeAsync: async msToRun => {\n        const fakeTimers = _getFakeTimers();\n\n        if (fakeTimers === this.environment.fakeTimersModern) {\n          await fakeTimers.advanceTimersByTimeAsync(msToRun);\n        } else {\n          throw new TypeError(\n            '`jest.advanceTimersByTimeAsync()` is not available when using legacy fake timers.',\n          );\n        }\n      },\n      advanceTimersToNextFrame: () => {\n        const fakeTimers = _getFakeTimers();\n\n        if (fakeTimers === this.environment.fakeTimersModern) {\n          return fakeTimers.advanceTimersToNextFrame();\n        }\n        throw new TypeError(\n          '`jest.advanceTimersToNextFrame()` is not available when using legacy fake timers.',\n        );\n      },\n      advanceTimersToNextTimer: steps =>\n        _getFakeTimers().advanceTimersToNextTimer(steps),\n      advanceTimersToNextTimerAsync: async steps => {\n        const fakeTimers = _getFakeTimers();","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/jestjs/jest/blob/f49721c78e195558b40913977c9230f5b7f559d8/packages/jest-runtime/src/internals/JestGlobals.ts#L285-L321","documentation":"TypeError thrown by `jest.advanceTimersByTimeAsync()` when the active fake timer implementation is the legacy one (`this.environment.fakeTimers`), not the modern one. The async timer APIs only exist on `@jest/fake-timers`' modern implementation, so calling them under legacy fake timers is unsupported.","triggerScenarios":"Calling `jest.advanceTimersByTimeAsync(ms)` after enabling legacy fake timers via `jest.useFakeTimers({ legacyFakeTimers: true })` or having `fakeTimers.legacyFakeTimers: true` in jest config.","commonSituations":"Inheriting a config with `fakeTimers: { legacyFakeTimers: true }`; explicitly opting into legacy timers for a specific behavior then forgetting and calling an async timer method; upgrading Jest and finding old tests relied on legacy timers.","solutions":["Switch to modern fake timers: `jest.useFakeTimers({ legacyFakeTimers: false })` (or remove the option — modern is default).","If you must keep legacy timers, use the sync `jest.advanceTimersByTime(ms)` instead of the async variant.","Remove `fakeTimers: { legacyFakeTimers: true }` from jest.config unless you have a specific reason."],"exampleFix":"// before\njest.useFakeTimers({ legacyFakeTimers: true });\nawait jest.advanceTimersByTimeAsync(1000); // throws\n\n// after\njest.useFakeTimers(); // modern (default)\nawait jest.advanceTimersByTimeAsync(1000);","handlingStrategy":"validation","validationCode":"// Detect which timer backend is active before calling async timer APIs\nfunction isLegacyTimers() {\n  // legacyFakeTimers is set via config or useFakeTimers; track it yourself:\n  return Boolean(globalThis.__LEGACY_FAKE_TIMERS__);\n}\nif (!isLegacyTimers()) {\n  await jest.advanceTimersByTimeAsync(1000);\n} else {\n  jest.advanceTimersByTime(1000);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to modern fake timers (omit legacyFakeTimers).","Centralize timer helper functions so the timer mode is decided in one place.","Add a lint rule or code-review check rejecting `legacyFakeTimers: true`."],"tags":["fake-timers","legacy","async","config"],"analyzedSha":"f49721c78e195558b40913977c9230f5b7f559d8","analyzedAt":"2026-08-03T20:16:28.571Z","schemaVersion":2}