vitest-dev/vitest · error · TypeError

Unexpected value for --expect.poll: ${value}. If you need to

Error message

Unexpected value for --expect.poll: ${value}. If you need to configure timeout, use --expect.poll.timeout=<timeout>

What it means

Thrown by the `--expect.poll` option transform when it receives a non-object value. `--expect.poll` is a container for sub-options (interval, timeout); it must be configured via dotted keys (`--expect.poll.timeout=<ms>`), not assigned a scalar directly.

Source

Thrown at packages/vitest/src/node/cli/cli-config.ts:815

      },
      poll: {
        description: 'Default options for `expect.poll()`',
        argument: '',
        subcommands: {
          interval: {
            description:
              'Poll interval in milliseconds for `expect.poll()` assertions (default: `50`)',
            argument: '<interval>',
          },
          timeout: {
            description:
              'Poll timeout in milliseconds for `expect.poll()` assertions (default: `1000`)',
            argument: '<timeout>',
          },
        },
        transform(value) {
          if (typeof value !== 'object') {
            throw new TypeError(
              `Unexpected value for --expect.poll: ${value}. If you need to configure timeout, use --expect.poll.timeout=<timeout>`,
            )
          }
          return value
        },
      },
    },
    transform(value) {
      if (typeof value !== 'object') {
        throw new TypeError(
          `Unexpected value for --expect: ${value}. If you need to configure expect options, use --expect.{name}=<value> syntax`,
        )
      }
      return value
    },
  },
  printConsoleTrace: {
    description: 'Always print console stack traces',

View on GitHub (pinned to d568f8ce37)

Solutions

1. Use the dotted key: `--expect.poll.timeout=<ms>` and/or `--expect.poll.interval=<ms>`.
2. If configuring in a file, use the object form `expect: { poll: { timeout: 1000 } }` rather than a scalar.

Example fix

# before
vitest --expect.poll=1000
# after
vitest --expect.poll.timeout=1000

if (typeof poll !== 'object' || poll === null) {
  throw new Error('expect.poll must be an object; use --expect.poll.timeout=<ms>')
}

function isPollOptions(v: unknown): v is { timeout?: number; interval?: number } {
  return v !== null && typeof v === 'object'
}

When it happens

Trigger: Passing `--expect.poll=1000` or `--expect.poll=50` (a number/string) instead of `--expect.poll.timeout=1000`. The transform checks `typeof value !== 'object'` and rejects scalars, pointing the user at the dotted syntax.

Common situations: Assuming --expect.poll takes a timeout value directly; copy-paste from docs that used the JS object form `{ poll: { timeout: 1000 } }` translated incorrectly to the CLI; shell scripts building the flag from a variable.

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