vitest-dev/vitest · error · TypeError

[vitest] vi.mock(" ", factory?: () => unknown) is not…

Error message

[vitest] vi.mock("${raw}", factory?: () => unknown) is not returning an object. Did you mean to return an object with a "default" key?

What it means

Thrown by assertValidExports when a manual mock factory's return value is null, a non-object, or an array. ManualMockedModule.resolve() runs the factory and asserts the exports are a plain object, because the module system expects a namespace object (with a 'default' key for default exports). Returning a primitive or forgetting to return is the most common cause.

Example fix

// before
vi.mock('./logger', () => console.log)
// after
vi.mock('./logger', () => ({ default: console.log, log: console.log }))

// Inside a vi.mock factory, validate before returning
vi.mock('./mod', () => {
  const exports = { default: 'x' }
  if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) {
    throw new TypeError('factory must return a plain object')
  }
  return exports
})

function isPlainObjectExports(v: unknown): v is Record<string, unknown> { return v !== null && typeof v === 'object' && !Array.isArray(v) }

When it happens

Trigger: A vi.mock factory that returns undefined (missing return statement), returns a string/number, returns null, or returns an array; an async factory whose promise resolves to a non-object. Triggered at module load time when the mocked module is first imported.

Common situations: Forgetting `return` in the factory arrow function; returning a class instance or function instead of wrapping it in { default: ... }; mock factory that conditionally returns; ESM default-export mock that returned the value directly instead of { default: value }.

Related errors

• [vitest] Manual mocks require a factory function.
• [vitest] Redirect mocks require a redirect string.
• vi.mock() expects a string path, but received a
• [@vitest/mocker] `createMockInstance` is not defined. This…
• Vitest mocker was not initialized in this environment. vi.

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/9982aa5d75f20470. Report an issue: GitHub.

Appendix: source

Thrown at packages/mocker/src/registry.ts:327

      id: this.id,
      raw: this.raw,
    }
  }
}

function createHelpfulError(cause: Error) {
  const error = new Error(
    '[vitest] There was an error when mocking a module. '
    + '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. '
    + 'Read more: https://vitest.dev/api/vi.html#vi-mock',
  )
  error.cause = cause
  return error
}

function assertValidExports(raw: string, exports: any) {
  if (exports === null || typeof exports !== 'object' || Array.isArray(exports)) {
    throw new TypeError(
      `[vitest] vi.mock("${raw}", factory?: () => unknown) is not returning an object. Did you mean to return an object with a "default" key?`,
    )
  }
}

export interface ManualMockedModuleSerialized {
  type: 'manual'
  url: string
  id: string
  raw: string
}

View on GitHub (pinned to 1fa9837ec2)