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

`vi.doUnmock(path)` is the non-hoisted counterpart of `vi.unmock` and also requires a string path. A non-string argument triggers a `TypeError` (with `typeof path`) before the unmock is queued in the browser mocker.

Solutions

1. Pass the path string matching a prior `vi.doMock`: `vi.doUnmock('./db')`.
2. Verify the argument type when the path is dynamic.
3. Distinguish from `vi.unmock` (hoisted) which also requires a string.

Example fix

// before
vi.doUnmock(dbNamespace)

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

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

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

When it happens

Trigger: Calling `vi.doUnmock(moduleNamespace)`, `vi.doUnmock(42)`, or any non-string identifier.

Common situations: Passing the imported module object instead of its path; refactor that swapped in a non-string; mixing hoisted and non-hoisted forms with mismatched argument types.

Related errors

• vi.doMock() 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/0ede60c5c0032e65. Report an issue: GitHub.

Appendix: source

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

      const importer = getImporter('doMock')
      _mocker().queueMock(
        path,
        importer,
        typeof factory === 'function'
          ? () =>
              factory(() =>
                _mocker().importActual(
                  path,
                  importer,
                ),
              )
          : factory,
      )
    },

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

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

    async importMock<T>(path: string): Promise<MaybeMockedDeep<T>> {
      return _mocker().importMock(path, getImporter('importMock'))
    },
  }
}

View on GitHub (pinned to 1fa9837ec2)