vitest-dev/vitest · error · TypeError

Unexpected value for --expect.poll

Error message

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

What it means

The `--expect.poll` sub-option only accepts an object form (`--expect.poll.interval=<ms>` and/or `--expect.poll.timeout=<ms>`). Supplying a scalar such as `--expect.poll=50` is rejected with a `TypeError` pointing to the `.timeout=` form, because the poll config is an object with named children, not a single number.

Solutions

1. Use the named sub-flags: `--expect.poll.interval=50 --expect.poll.timeout=1000`.
2. If you only need the timeout: `--expect.poll.timeout=2000`.
3. Prefer setting `expect.pollInterval`/`expect.pollTimeout` in the config file for readability.

Example fix

# before
vitest run --expect.poll=200

# after
vitest run --expect.poll.interval=50 --expect.poll.timeout=1000

type PollConfig = { interval?: number; timeout?: number }
function parsePollCli(value: unknown): PollConfig {
  if (value && typeof value === 'object') return value as PollConfig
  throw new TypeError('Use --expect.poll.interval=<ms> and/or --expect.poll.timeout=<ms>')
}

function isPollConfig(v: unknown): v is PollConfig {
  return typeof v === 'object' && v !== null
    && (v as any).interval === undefined || typeof (v as any).interval === 'number'
    && (v as any).timeout === undefined || typeof (v as any).timeout === 'number'
}

When it happens

Trigger: Running `vitest --expect.poll=200`, `--expect.poll true`, or any value where `typeof value !== 'object'` inside the `expect.poll` transform.

Common situations: Migrating an `expect.pollInterval`/`expect.pollTimeout` config from a previous version and assuming the CLI mirrors it as a scalar; treating the poll option as a boolean enable flag.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Unexpected value for --expect
• Unexpected value "--silent=
• Exact option does not support RegExp expected class names
• expect.poll() is not supported in combination with .resolves
• expect.poll() is not supported in combination with .rejects

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

Appendix: 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 1fa9837ec2)