vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

Thrown at packages/mocker/src/browser/hints.ts:63-67 as a TypeError when vi.mock() is called with a first argument that is not a string. vi.mock needs a module specifier to resolve and register the mock; the type guard rejects non-string paths before they reach the registry.

Source

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

              )
            },
          },
        )
  }

  return {
    hoisted<T>(factory: () => T): T {
      if (typeof factory !== 'function') {
        throw new TypeError(
          `vi.hoisted() expects a function, but received a ${typeof factory}`,
        )
      }
      return factory()
    },

    mock(path: string | Promise<unknown>, factory?: ModuleMockOptions | ModuleMockFactoryWithHelper): void {
      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,
                ),
              )
          : factory,
      )
    },

View on GitHub (pinned to d568f8ce37)

Solutions

1. Pass a string literal module path: vi.mock('./logger').
2. If using a variable, ensure it is typed and assigned a string before the call.
3. Avoid passing import() expressions directly; let the transformer rewrite them or use a plain string.

Example fix

// before
vi.mock(import('./logger'))

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

// Ensure the path is a string before calling vi.mock.
function mockIfString(path: unknown, factory?: () => any) {
  if (typeof path !== 'string') {
    throw new TypeError(`vi.mock requires a string path, got ${typeof path}`)
  }
  vi.mock(path, factory)
}

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

When it happens

Trigger: Calling vi.mock(someVariable) where the variable is undefined/not a string; vi.mock(import('./x')) where the dynamic import was not rewritten to its source by the transform; vi.mock(123) or vi.mock({}).

Common situations: Passing a dynamic import expression that the hoistMocks transform failed to rewrite (hoistMocks.ts:344-371); passing a path from configuration that resolved to undefined; template strings that evaluated to non-string.

Related errors

• vi.unmock() expects a string path, but received a ${typeof p
• vi.doMock() expects a string path, but received a ${typeof p
• vi.doUnmock() expects a string path, but received a ${typeof
• vi.hoisted() expects a function, but received a ${typeof fac
• toHaveFormValues must be called on a form or a fieldset, ins

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