vitest-dev/vitest · error · TypeError

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

Error message

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

What it means

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

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 d568f8ce37)

Solutions

1. Use the dotted key for the specific expect option, e.g. `--expect.requireAssertions`.
2. In a config file, use the object form `expect: { requireAssertions: true }`.

Example fix

# before
vitest --expect=requireAssertions
# after
vitest --expect.requireAssertions

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

function isExpectOptions(v: unknown): v is Record<string, unknown> {
  return v !== null && typeof v === 'object'
}

When it happens

Trigger: Passing `--expect=requireAssertions` as a value (string) instead of `--expect.requireAssertions`, or any scalar assigned to `--expect`. The transform checks `typeof value !== 'object'` and rejects scalars.

Common situations: Misreading the dotted-option syntax; trying to enable a boolean sub-option by attaching it as the parent flag's value; converting a config object to CLI flags incorrectly.

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