{"id":"1d959c71d8ad6c92","repo":"vitest-dev/vitest","slug":"a-function-to-advance-timers-was-called-but-the-ti","errorCode":null,"errorMessage":"A function to advance timers was called but the timers APIs are not mocked. Call `vi.useFakeTimers()` in the test file first.","messagePattern":"A function to advance timers was called but the timers APIs are not mocked\\. Call `vi\\.useFakeTimers\\(\\)` in the test file first\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/integrations/mock/timers.ts","lineNumber":260,"sourceCode":"        this._clock.setTickMode({ mode: 'interval', delta: interval })\n      }\n      else {\n        throw new Error(`Invalid tick mode: ${mode}`)\n      }\n    }\n  }\n\n  configure(config: FakeTimersConfig): void {\n    this._userConfig = config\n  }\n\n  isFakeTimers(): boolean {\n    return this._fakingTime\n  }\n\n  private _checkFakeTimers() {\n    if (!this._fakingTime) {\n      throw new Error(\n        'A function to advance timers was called but the timers APIs are not mocked. '\n        + 'Call `vi.useFakeTimers()` in the test file first.',\n      )\n    }\n\n    return this._fakingTime\n  }\n}\n","sourceCodeStart":242,"sourceCodeEnd":269,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/integrations/mock/timers.ts#L242-L269","documentation":"Every timer-advancing API (`advanceTimersByTime`, `runAllTimers`, `runOnlyPendingTimers`, `advanceTimersToNextTimer`, `runAllTicks`, `getTimerCount`, etc.) is guarded by `_checkFakeTimers()`, which throws unless `vi.useFakeTimers()` has installed the fake clock (`_fakingTime === true`). This surfaces a forgotten setup call as an explicit error instead of silently operating on real timers.","triggerScenarios":"Calling `vi.advanceTimersByTime(n)`, `vi.runAllTimers()`, `vi.advanceTimersToNextTimer()`, `vi.runAllTicks()`, etc. without a preceding `vi.useFakeTimers()` in the same test, or after `vi.useRealTimers()` restored the real clock.","commonSituations":"Forgetting `vi.useFakeTimers()` in a new test, calling advance in `beforeAll` but using real timers per-test, or restoring real timers mid-test and then advancing.","solutions":["Call `vi.useFakeTimers()` at the start of the test (or in `beforeEach`) before any timer-advance call.","If you called `vi.useRealTimers()`, re-enable fakes with `vi.useFakeTimers()` before advancing again.","Guard shared helpers so they enable fake timers before advancing."],"exampleFix":"// before\nit('fires callback', () => {\n  const cb = vi.fn()\n  setTimeout(cb, 1000)\n  vi.advanceTimersByTime(1000) // throws\n})\n// after\nit('fires callback', () => {\n  vi.useFakeTimers()\n  const cb = vi.fn()\n  setTimeout(cb, 1000)\n  vi.advanceTimersByTime(1000)\n})","handlingStrategy":"validation","validationCode":"import { vi } from 'vitest'\nif (!vi.isFakeTimers()) {\n  vi.useFakeTimers()\n}\nvi.advanceTimersByTime(1000)","typeGuard":"import { vi } from 'vitest'\n// vi.isFakeTimers(): boolean — the public guard before advancing","tryCatchPattern":null,"preventionTips":["Call `vi.useFakeTimers()` at the start of every test that advances timers.","After `vi.useRealTimers()`, re-enable fakes before advancing.","Use `vi.isFakeTimers()` in shared helpers to gate advance calls."],"tags":["timers","fake-timers","setup","assertion"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}