{"id":"9982aa5d75f20470","repo":"vitest-dev/vitest","slug":"vitest-vi-mock-raw-factory-unknown","errorCode":null,"errorMessage":"[vitest] vi.mock(\"${raw}\", factory?: () => unknown) is not returning an object. Did you mean to return an object with a \"default\" key?","messagePattern":"\\[vitest\\] vi\\.mock\\(\"(.+?)\", factory\\?: \\(\\) => unknown\\) is not returning an object\\. Did you mean to return an object with a \"default\" key\\?","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/mocker/src/registry.ts","lineNumber":327,"sourceCode":"      id: this.id,\n      raw: this.raw,\n    }\n  }\n}\n\nfunction createHelpfulError(cause: Error) {\n  const error = new Error(\n    '[vitest] There was an error when mocking a module. '\n    + 'If you are using \"vi.mock\" factory, make sure there are no top level variables inside, since this call is hoisted to top of the file. '\n    + 'Read more: https://vitest.dev/api/vi.html#vi-mock',\n  )\n  error.cause = cause\n  return error\n}\n\nfunction assertValidExports(raw: string, exports: any) {\n  if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) {\n    throw new TypeError(\n      `[vitest] vi.mock(\"${raw}\", factory?: () => unknown) is not returning an object. Did you mean to return an object with a \"default\" key?`,\n    )\n  }\n}\n\nexport interface ManualMockedModuleSerialized {\n  type: 'manual'\n  url: string\n  id: string\n  raw: string\n}\n","sourceCodeStart":309,"sourceCodeEnd":339,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/mocker/src/registry.ts#L309-L339","documentation":"A `vi.mock` factory must return a module-namespace object — either `{ default, ...named }` or a bag of named exports. `assertValidExports` rejects `null`, primitives, and arrays because none of them represent a valid ES/CJS module shape, and the most common cause is forgetting to wrap a single value under a `default` key.","triggerScenarios":"`vi.mock('m', () => 42)`, `() => null`, `() => [1, 2, 3]`, `() => 'string'`, or an async factory returning a non-object. Also fires if the factory returns a Promise that resolves to a non-object.","commonSituations":"Mocking a default export and returning the value directly instead of `{ default: value }`; returning a class instance meant as the default; returning an array of items; factory that conditionally returns `null`.","solutions":["Wrap a single value as the default export: `() => ({ default: value })`.","Return named exports as an object: `() => ({ add: vi.fn(), sub: vi.fn() })`.","For async factories, resolve to an object: `async () => ({ default: await load() })`."],"exampleFix":"// before\nvi.mock('./db', () => 42)\n\n// after\nvi.mock('./db', () => ({\n  default: 42,\n}))","handlingStrategy":"validation","validationCode":"function mockModule(specifier: string, factory: () => unknown) {\n  const exports = factory()\n  if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) {\n    throw new TypeError(\n      `vi.mock('${specifier}') factory must return an object (module namespace). ` +\n      `Wrap a single value: () => ({ default: value }).`,\n    )\n  }\n  vi.mock(specifier, factory as () => any)\n}","typeGuard":"function isValidMockExports(v: unknown): v is Record<string, unknown> {\n  return v !== null && typeof v === 'object' && !Array.isArray(v)\n}","tryCatchPattern":null,"preventionTips":["Always return `{ default: value }` for single-value mocks and `{ name: fn }` for named exports.","Never return arrays, null, or primitives from a `vi.mock` factory.","For async factories, resolve to an object before returning."],"tags":["mocking","vi-mock","validation","manual-mock"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}