vitest-dev/vitest · error · TypeError

vi.unmock() expects a string path, but received a ${typeof p

Error message

vi.unmock() expects a string path, but received a ${typeof path}

What it means

`vi.unmock(path)` is the counterpart of `vi.mock`, removing a previously queued mock for the given string module path. Like `vi.mock`, it rejects non-string `path` values with a `TypeError` because the mocker can only look up mocks by resolved string path. The signature types `path` as `string | Promise<unknown>` but enforces string at runtime.

Source

Thrown at packages/vitest/src/integrations/vi.ts:671

      _mocker().queueMock(
        path,
        importer,
        typeof factory === 'function'
          ? () =>
              factory(() =>
                _mocker().importActual(
                  path,
                  importer,
                  _mocker().getMockContext().callstack,
                ),
              )
          : factory,
      )
    },

    unmock(path: string | Promise<unknown>) {
      if (typeof path !== 'string') {
        throw new TypeError(
          `vi.unmock() expects a string path, but received a ${typeof path}`,
        )
      }
      _mocker().queueUnmock(path, getImporter('unmock'))
    },

    doMock(path: string | Promise<unknown>, factory?: MockOptions | MockFactoryWithHelper) {
      if (typeof path !== 'string') {
        throw new TypeError(
          `vi.doMock() expects a string path, but received a ${typeof path}`,
        )
      }
      const importer = getImporter('doMock')
      _mocker().queueMock(
        path,
        importer,
        typeof factory === 'function'
          ? () =>

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass the module specifier as a literal string: `vi.unmock('./api')`.
2. Ensure any dynamic path variable is a string before calling.
3. Use `vi.doUnmock` with a runtime string for non-literal paths.

Example fix

// before
vi.unmock(import('./api'))
// after
vi.unmock('./api')

function unmockPath(path: unknown) {
  if (typeof path !== 'string') throw new TypeError(`vi.unmock expects string, got ${typeof path}`)
  vi.unmock(path)
}

function isModulePath(v: unknown): v is string { return typeof v === 'string' && v.length > 0 }

When it happens

Trigger: Calling `vi.unmock(123)`, `vi.unmock(someObject)`, `vi.unmock(import('./mod'))`, or `vi.unmock(undefined)`.

Common situations: Passing a module namespace or promise instead of the specifier string, or a variable that resolved to a non-string.

Related errors

• vi.mock() expects a string path, but received a ${typeof pat
• [vitest] vi.mock("${raw}", factory?: () => unknown) is not r
• ${utils.inspect(chain)} is not a `vi.when` instance
• vi.when: the argument must be a mock function created with `
• vi.when: `times` option must be greater than 0

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/d089461bdc8a2ed6.json. Report an issue: GitHub.