jestjs/jest · error · TypeError

`jest.advanceTimersToNextFrame()` is not available when usin

Error message

`jest.advanceTimersToNextFrame()` is not available when using legacy fake timers.

What it means

TypeError thrown by `jest.advanceTimersToNextFrame()` when legacy fake timers are active. `advanceTimersToNextFrame` is a modern-fake-timers-only API (advances to the next requestAnimationFrame tick) and has no legacy implementation.

Source

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

        _getFakeTimers().advanceTimersByTime(msToRun),
      advanceTimersByTimeAsync: async msToRun => {
        const fakeTimers = _getFakeTimers();

        if (fakeTimers === this.environment.fakeTimersModern) {
          await fakeTimers.advanceTimersByTimeAsync(msToRun);
        } else {
          throw new TypeError(
            '`jest.advanceTimersByTimeAsync()` is not available when using legacy fake timers.',
          );
        }
      },
      advanceTimersToNextFrame: () => {
        const fakeTimers = _getFakeTimers();

        if (fakeTimers === this.environment.fakeTimersModern) {
          return fakeTimers.advanceTimersToNextFrame();
        }
        throw new TypeError(
          '`jest.advanceTimersToNextFrame()` is not available when using legacy fake timers.',
        );
      },
      advanceTimersToNextTimer: steps =>
        _getFakeTimers().advanceTimersToNextTimer(steps),
      advanceTimersToNextTimerAsync: async steps => {
        const fakeTimers = _getFakeTimers();

        if (fakeTimers === this.environment.fakeTimersModern) {
          await fakeTimers.advanceTimersToNextTimerAsync(steps);
        } else {
          throw new TypeError(
            '`jest.advanceTimersToNextTimerAsync()` is not available when using legacy fake timers.',
          );
        }
      },
      autoMockOff: disableAutomock,
      autoMockOn: enableAutomock,

View on GitHub (pinned to f49721c78e)

Solutions

Use modern fake timers: `jest.useFakeTimers()` (default) and remove `legacyFakeTimers: true`.
If legacy timers are required for other reasons, manually advance time with `jest.advanceTimersByTime(16)` as an approximation for one frame.

Example fix

// before
jest.useFakeTimers({ legacyFakeTimers: true });
jest.advanceTimersToNextFrame(); // throws

// after
jest.useFakeTimers();
jest.advanceTimersToNextFrame();

Defensive patterns

Strategy: validation

Validate before calling

// Standardize on modern timers in a shared setup helper
function withModernFakeTimers(fn) {
  return () => {
    jest.useFakeTimers(); // modern
    fn();
  };
}

Prevention

Avoid `legacyFakeTimers: true` in jest.config — modern timers support rAF.
Wrap rAF-based timer helpers so they only run under modern timers.

When it happens

Trigger: Calling `jest.advanceTimersToNextFrame()` while `legacyFakeTimers: true` is set (via config or `useFakeTimers({ legacyFakeTimers: true })`).

Common situations: Testing rAF-based code with legacy timers enabled by an old config; team-wide config defaulting to legacy timers while individual tests use modern-only rAF helpers.

Related errors

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