vitest-dev/vitest · error · SyntaxError

expect.poll() is not supported in combination with .resolves

Error message

expect.poll() is not supported in combination with .resolves

What it means

`.resolves` is a Chai property that flags the assertion to wait for promise resolution. Vitest's `expect.poll()` already drives retries, and combining the two is undefined, so the code raises a `SyntaxError` before setting up the proxy. It is a usage error, not a runtime data error.

Source

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

  def('withContext', function (this: any, context: Record<string, any>) {
    for (const key in context) {
      utils.flag(this, key, context[key])
    }
    return this
  })

  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
          }

View on GitHub (pinned to 1fa9837ec2)

Solutions

Drop `.resolves` when using `expect.poll` — poll already unwraps the value via the callback.
If you need promise semantics, use `expect(promise).resolves...` without `poll`.
Return a non-promise value from the poll callback and assert directly.

Example fix

// before
expect.poll(() => fetchResult()).resolves.toEqual(data)

// after
expect.poll(() => fetchResult()).toEqual(data)

Defensive patterns

Strategy: validation

Validate before calling

// never combine .resolves with expect.poll
// assert directly on the polled value instead

Prevention

Drop .resolves/.rejects when adopting expect.poll.
Treat poll as the single retry mechanism for the assertion.
Lint for .resolves/.rejects chained on expect.poll in code review.

When it happens

Trigger: Writing `expect.poll(() => p).resolves.toBe(...)` or chaining `.resolves` onto an assertion whose subject came from `expect.poll()`.

Common situations: Migrating a flaky promise test to `expect.poll` and forgetting to drop `.resolves`; copy-paste from a resolves-based test into a poll wrapper.

Related errors

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