vitest-dev/vitest · error · TypeError

Unexpected value for --expect

Error message

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

What it means

The top-level `--expect` option is an object whose children are `--expect.{name}=<value>`. Passing a scalar to `--expect` itself (e.g. `--expect=foo`) is rejected because `typeof value !== 'object'` in its `transform`. The message directs users to the dotted-key syntax.

Solutions

Use dotted keys for the property you want: `--expect.poll.timeout=1000`, `--expect.assertions=5`, etc.
If you wanted no expect customization, remove the flag entirely.
Set the same values via the config file's `test.expect` object.

Example fix

# before
vitest run --expect=foo

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

Defensive patterns

Strategy: validation

Validate before calling

function assertExpectObject(v: unknown): asserts v is Record<string, unknown> {
  if (v != null && typeof v !== 'object') {
    throw new TypeError('--expect must be an object; use --expect.<name>=<value>')
  }
}

Prevention

Never pass a scalar to `--expect`; always use dotted sub-keys.
Configure expect defaults in `test.expect` of the config file.
Audit shell aliases that append values to flags.

When it happens

Trigger: `vitest --expect=foo`, `--expect 5`, or any non-object value reaching the outer `expect.transform`.

Common situations: Treating `--expect` as a feature toggle; misreading docs and passing an assertion filter through `--expect`; shell alias that concatenates a value onto `--expect`.

Related errors

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

Appendix: source

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

          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',
  },
  includeTaskLocation: {
    description: 'Collect test and suite locations in the `location` property',
  },
  attachmentsDir: {
    description: 'The directory where attachments from `context.annotate` are stored in (default: `.vitest/attachments`)',
    argument: '<dir>',
  },

  // CLI only options

View on GitHub (pinned to 1fa9837ec2)