vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

Thrown by `vi.doUnmock(path)` when `path` is not a string. `vi.doUnmock` is the non-hoisted counterpart to `vi.unmock` and requires a string module specifier so the mocker can queue the unmock against the importer's call stack. Any non-string argument raises a TypeError.

Solutions

1. Pass a string specifier: `vi.doUnmock('./myModule')`.
2. Verify the argument is a string at call time when computed dynamically.
3. Ensure you pass the path string, not the imported binding.

Example fix

// before
import * as M from './myModule'
vi.doUnmock(M)

// after
vi.doUnmock('./myModule')

function doUnmockSafe(path) {
  if (typeof path !== 'string') throw new TypeError('vi.doUnmock requires a string path')
  return vi.doUnmock(path)
}

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

When it happens

Trigger: Calling `vi.doUnmock(nonString)`; passing an imported module namespace, a Promise, or a number; using a variable that is undefined at call time.

Common situations: Pairing `vi.doMock` with `vi.doUnmock` but passing the wrong argument type; refactoring that drops the literal path; misunderstanding the required specifier form.

Related errors

• vi.doMock() expects a string path, but received a
• vi.doUnmock() expects a string path, but received a
• vi.mock() expects a string path, but received a
• vi.unmock() expects a string path, but received a
• any() expects to be passed a constructor function. Please…

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/61c62197c4519f60. Report an issue: GitHub.

Appendix: 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 1fa9837ec2)