{"id":"c7a579bc6e891043","repo":"vitest-dev/vitest","slug":"vi-domock-expects-a-string-path-but-received-a-c7a579","errorCode":null,"errorMessage":"vi.doMock() expects a string path, but received a ${typeof path}","messagePattern":"vi\\.doMock\\(\\) expects a string path, but received a (.+?)","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/vitest/src/integrations/vi.ts","lineNumber":680,"sourceCode":"                  _mocker().getMockContext().callstack,\n                ),\n              )\n          : factory,\n      )\n    },\n\n    unmock(path: string | Promise<unknown>) {\n      if (typeof path !== 'string') {\n        throw new TypeError(\n          `vi.unmock() expects a string path, but received a ${typeof path}`,\n        )\n      }\n      _mocker().queueUnmock(path, getImporter('unmock'))\n    },\n\n    doMock(path: string | Promise<unknown>, factory?: MockOptions | MockFactoryWithHelper) {\n      if (typeof path !== 'string') {\n        throw new TypeError(\n          `vi.doMock() expects a string path, but received a ${typeof path}`,\n        )\n      }\n      const importer = getImporter('doMock')\n      _mocker().queueMock(\n        path,\n        importer,\n        typeof factory === 'function'\n          ? () =>\n              factory(() =>\n                _mocker().importActual(\n                  path,\n                  importer,\n                  _mocker().getMockContext().callstack,\n                ),\n              )\n          : factory,\n      )","sourceCodeStart":662,"sourceCodeEnd":698,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/src/integrations/vi.ts#L662-L698","documentation":"Thrown by vi.doMock() when its first argument is not a string. The method's TypeScript signature accepts `string | Promise<unknown>` only to keep the compiler happy for dynamic-import-style call sites, but at runtime the mocker needs a resolvable module specifier string. Receiving anything else (undefined, an object, a number) means the call cannot queue a mock and Vitest fails fast with a TypeError rather than silently no-oping.","triggerScenarios":"Calling vi.doMock() with a non-string first argument: vi.doMock(undefined), vi.doMock(someModuleObject), vi.doMock(42), or passing a variable whose value is undefined at runtime. Also triggered by spreading arguments incorrectly, e.g. vi.doMock(...someArray) where the first element is not a string.","commonSituations":"Refactoring an import and forgetting to update the literal path passed to vi.doMock; dynamically computing a module path that resolves to undefined; copy-paste from vi.mock() (which is hoisted and string-only) into a doMock call while reusing a non-string variable; TS loose typing hiding the bug because the union includes Promise<unknown>.","solutions":["Pass a string module specifier: vi.doMock('./path/to/module', factory).","If the path comes from a variable, add a runtime check `if (typeof p === 'string')` or assert it before calling doMock.","Enable strict TypeScript checking on the call site so non-string values are caught at compile time (note the signature is intentionally permissive, so also rely on code review).","If you intended to pass a Promise from import(), await it or use the string literal directly — doMock does not accept awaited modules either."],"exampleFix":"// before\nconst mod = await import('./lib')\nvi.doMock(mod)\n// after\nvi.doMock('./lib', () => mockFactory)","handlingStrategy":"type-guard","validationCode":"if (typeof path !== 'string') {\n  throw new Error('doMock requires a string module path')\n}\nvi.doMock(path, factory)","typeGuard":"function isMockPath(path: unknown): path is string {\n  return typeof path === 'string' && path.length > 0\n}","tryCatchPattern":null,"preventionTips":["Always pass a string literal module specifier to vi.doMock.","If the path is dynamic, assert/guard its type before the call.","Review call sites during refactors that touch imports."],"tags":[],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}