vitest-dev/vitest · error · TypeError

You must provide a Promise to expect() when using…

Error message

You must provide a Promise to expect() when using .resolves, not '${typeof obj}'.

What it means

`.resolves` requires a thenable as the subject of `expect()`. If `obj.then` is not a function (including when `obj` is null/undefined or a plain value), the matcher cannot await it and throws a `TypeError`. This guards the async machinery before constructing the proxy.

Solutions

Return a Promise from the subject under test, or remove `.resolves` if the value is not a promise.
Add `async` to the producer so it consistently returns a Promise.
Use `await` correctly so you pass the promise itself to `expect()`.

Example fix

// before
expect(getValue()).resolves.toBe(42) // getValue returns 42 synchronously

// after
expect(getValue()).toBe(42)

Defensive patterns

Strategy: type-guard

Validate before calling

const isThenable = (v: unknown): v is PromiseLike<unknown> =>
  !!v && typeof (v as any).then === 'function'
if (!isThenable(value)) { throw new Error('pass a Promise when using .resolves') }

Type guard

const isPromise = (v: unknown): v is Promise<unknown> =>
  !!v && typeof (v as any).then === 'function'

Prevention

Make the producer consistently async so it returns a Promise.
Pass the promise itself, not its resolved value, to expect().
Remove .resolves when the subject is not a promise.

When it happens

Trigger: `expect(42).resolves.toBe(42)`, `expect(null).resolves...`, or passing a value from a function that returned synchronously instead of a Promise.

Common situations: Forgetting `await`/`return` so the actual subject is the resolved value, not the promise; calling `.resolves` on a number, string, or object; a function that returns a value rather than a promise in the non-async code path.

Related errors

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

Appendix: source

Thrown at packages/expect/src/jest-expect.ts:1091

  utils.addProperty(
    chai.Assertion.prototype,
    'resolves',
    function __VITEST_RESOLVES__(this: any) {
      const error = new Error('resolves')
      utils.flag(this, 'promise', 'resolves')
      utils.flag(this, 'error', error)
      const test: Test = utils.flag(this, 'vitest-test')
      const obj = utils.flag(this, 'object')

      if (utils.flag(this, 'poll')) {
        throw new SyntaxError(
          `expect.poll() is not supported in combination with .resolves`,
        )
      }

      if (typeof obj?.then !== 'function') {
        throw new TypeError(
          `You must provide a Promise to expect() when using .resolves, not '${typeof obj}'.`,
        )
      }

      const proxy: any = new Proxy(this, {
        get: (target, key, receiver) => {
          const result = Reflect.get(target, key, receiver)

          if (typeof result !== 'function') {
            return result instanceof chai.Assertion ? proxy : result
          }

          return (...args: any[]) => {
            utils.flag(this, '_name', key)
            const promise = Promise.resolve(obj).then(
              (value: any) => {
                utils.flag(this, 'object', value)
                return result.call(this, ...args)

View on GitHub (pinned to 1fa9837ec2)