vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

Thrown by vi.doUnmock() when its first argument is not a string. doUnmock queues removal of a previously queued mock for a module specifier; without a concrete string path the mocker cannot match the entry to remove. Like doMock, the parameter type is permissive (`string | Promise<unknown>`) but only strings are honored at runtime.

Source

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

                  importer,
                  _mocker().getMockContext().callstack,
                ),
              )
          : factory,
      )

      const rv = {} as Disposable
      if (Symbol.dispose) {
        rv[Symbol.dispose] = () => {
          _mocker().queueUnmock(path, importer)
        }
      }
      return rv
    },

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

    async importActual<T = unknown>(path: string): Promise<T> {
      const importer = getImporter('importActual')
      return _mocker().importActual<T>(
        path,
        importer,
        _mocker().getMockContext().callstack,
      )
    },

    async importMock<T>(path: string): Promise<MaybeMockedDeep<T>> {
      const importer = getImporter('importMock')

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass the same string specifier you would pass to vi.doMock: vi.doUnmock('./path/to/module').
2. Guard the variable with a typeof check before calling doUnmock.
3. Use a using/await using binding returned by vi.doMock to auto-unmock instead of calling doUnmock manually.

Example fix

// before
vi.doUnmock(myModuleObject)
// after
vi.doUnmock('./path/to/myModule')

if (typeof path !== 'string') {
  throw new Error('doUnmock requires a string module path')
}
vi.doUnmock(path)

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

When it happens

Trigger: Calling vi.doUnmock() with undefined, an object, a number, or any non-string value. Commonly happens when the same variable used in a failed doMock is reused in doUnmock, or when destructuring a module object and passing it instead of its import path.

Common situations: Pairing vi.doUnmock with a dynamically-resolved module reference that is undefined; refactoring that changes a path variable type; migrating from vi.unmock (hoisted) to vi.doUnmock (not hoisted) and accidentally passing a module object.

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