vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

`vi.doMock(path, factory)` is the non-hoisted sibling of `vi.mock` and likewise requires a string path. The browser hints layer throws a `TypeError` (reporting `typeof path`) for any non-string first argument before queueing the mock.

Solutions

1. Pass the module path as a string: `vi.doMock('./db', factory)`.
2. Resolve the path string before calling when it is computed at runtime.
3. Use `vi.mocked` for typing an imported mock, not `vi.doMock`.

Example fix

// before
vi.doMock(await import('./db'))

// after
vi.doMock('./db', () => ({ query: vi.fn() }))

if (typeof path !== 'string') {
  throw new TypeError(`vi.doMock requires a string path, got ${typeof path}`)
}

const isPathString = (v: unknown): v is string => typeof v === 'string'

When it happens

Trigger: Calling `vi.doMock(moduleObject)`, `vi.doMock(Promise)`, or any non-string; using `vi.doMock` with an imported binding rather than its path.

Common situations: Switching from `vi.mock` to `vi.doMock` for runtime-specified modules but passing an object; dynamic-import helpers that yield a module namespace instead of a path string.

Related errors

• vi.doUnmock() expects a string path, but received a
• vi.hoisted() expects a function, but received a
• vi.mock() expects a string path, but received a
• vi.unmock() expects a string path, but received a
• The " " browser provider does not provide a…

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

Appendix: source

Thrown at packages/mocker/src/browser/hints.ts:95

                  importer,
                ),
              )
          : factory,
      )
    },

    unmock(path: string | Promise<unknown>): void {
      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?: ModuleMockOptions | ModuleMockFactoryWithHelper): void {
      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'
          ? () =>
              factory(() =>
                _mocker().importActual(
                  path,
                  importer,
                ),
              )
          : factory,
      )
    },

View on GitHub (pinned to 1fa9837ec2)