vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

Thrown by `vi.mock(path, factory)` when `path` is not a string. `vi.mock` is hoisted by the Vitest transformer and must receive a module specifier (string literal in source); passing a non-string (Promise, number, object, dynamic value) breaks hoisting and module resolution, so a TypeError is raised immediately.

Solutions

1. Pass a string literal path: `vi.mock('./myModule', () => {...})`.
2. If the path must be dynamic, use `vi.doMock` inside the test body (still requires a string) — but prefer a static literal for hoisting.
3. Ensure you are not passing the imported module object (e.g. `import * as M` then `vi.mock(M)`).

Example fix

// before
const modPath = './myModule'
vi.mock(modPath)

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

function mockSafe(path, factory) {
  if (typeof path !== 'string') throw new TypeError('vi.mock requires a string path')
  return vi.mock(path, factory)
}

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

When it happens

Trigger: Calling `vi.mock(someVariable)` where the variable is not a string; passing a Promise or imported module object; using a dynamic/conditional path; accidentally passing the module namespace object instead of its specifier.

Common situations: Trying to mock a path computed at runtime; passing an imported binding instead of a path string; refactoring that replaces the literal with a variable; misunderstanding that `vi.mock` must be statically analyzable.

Related errors

• vi.unmock() expects a string path, but received a
• 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
• 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/3797218f7f3fd750. Report an issue: GitHub.

Appendix: source

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

            catch (error) {
              if (error instanceof Error && !error.stack?.includes('__VITEST_HELPER__')) {
                copyStackTrace(error, stackTraceError)
              }
              throw error
            }
          })()
        }
        return result
      } as any
    },
    hoisted<T>(factory: () => T): T {
      assertTypes(factory, '"vi.hoisted" factory', ['function'])
      return factory()
    },

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

View on GitHub (pinned to 1fa9837ec2)