vitest-dev/vitest · error · TypeError

Cannot use `${shorthand}` when called with `new`. Use `mockI

Error message

Cannot use `${shorthand}` when called with `new`. Use `mockImplementation` with a `class` keyword instead. See https://vitest.dev/api/mock#class-support for more information.

What it means

Thrown by throwConstructorError() in packages/spy/src/index.ts when a mock configured with a shorthand return-style method (mockReturnValue, mockReturnValueOnce, mockResolvedValue, mockResolvedValueOnce, mockRejectedValue, mockRejectedValueOnce) is invoked with new. The shorthand implementations return a value, which is meaningless as a constructor result; Vitest requires an explicit mockImplementation(function/class){...}) so the mock can be instantiated. The guard fires inside the implementation via new.target.

Source

Thrown at packages/spy/src/index.ts:716

}

export function restoreAllMocks(): void {
  for (const restore of MOCK_RESTORE) {
    restore()
  }
  MOCK_RESTORE.clear()
}

export function clearAllMocks(): void {
  REGISTERED_MOCKS.forEach(mock => mock.mockClear())
}

export function resetAllMocks(): void {
  REGISTERED_MOCKS.forEach(mock => mock.mockReset())
}

function throwConstructorError(shorthand: string): never {
  throw new TypeError(
    `Cannot use \`${shorthand}\` when called with \`new\`. Use \`mockImplementation\` with a \`class\` keyword instead. See https://vitest.dev/api/mock#class-support for more information.`,
  )
}

export type {
  Constructable,
  MaybeMocked,
  MaybeMockedConstructor,
  MaybeMockedDeep,
  MaybePartiallyMocked,
  MaybePartiallyMockedDeep,
  Mock,
  MockContext,
  Mocked,
  MockedClass,
  MockedFunction,
  MockedFunctionDeep,
  MockedObject,

View on GitHub (pinned to d568f8ce37)

Solutions

Replace the shorthand with mockImplementation using a function or class: Mock.mockImplementation(function (...) { return {...} }).
Use vi.fn(class { ... }) if you need a real constructable mock.
Avoid new on mocks set up with mockResolvedValue/mockRejectedValue — those only make sense for function calls returning promises.
If you need both call and construct behavior, provide a mockImplementation that branches on new.target.

Example fix

// before
const Mock = vi.fn()
Mock.mockReturnValue({ id: 1 })
new Mock()

// after
const Mock = vi.fn()
Mock.mockImplementation(function () { return { id: 1 } })
new Mock()

Defensive patterns

Strategy: type-guard

Validate before calling

function isConstructableShorthand(setup: unknown): boolean {
  // detect shorthand-return configurations that cannot be used with `new`
  return typeof setup === 'function'
}

Type guard

const looksLikeClass = (v: unknown): boolean =>
  typeof v === 'function' && /^class\s/.test(Function.prototype.toString.call(v))

Prevention

Never pair mockReturnValue/mockResolvedValue/mockRejectedValue with new Mock().
Use mockImplementation(function|class) when the mock must be instantiated.
Branch on new.target in mockImplementation if a single mock must support both call and construct.

When it happens

Trigger: const Mock = vi.fn(); Mock.mockReturnValue({}); new Mock(); — i.e. constructing an instance from a mock whose implementation was set with a 'return value' shorthand.

Common situations: Mocking a class but using mockReturnValue to supply the instance; refactoring a function into a class without updating the mock setup; copy-pasting a function mock pattern onto a constructor.

Related errors

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