vitest-dev/vitest · error · Error

Unrecognized comparator

Error message

Unrecognized comparator ${comparator}

What it means

Thrown by `getComparator` when the requested comparator name is neither the built-in `'pixelmatch'` nor a key in the user-provided `browser.expect.toMatchScreenshot.comparators` config map. The comparator is the function that diffs the decoded reference against the captured screenshot; an unknown name means no diffing strategy is available, so the matcher aborts during option resolution.

Solutions

1. Use the default `'pixelmatch'` comparator (omit the `comparator` option).
2. Register a custom comparator under `test.browser.expect.toMatchScreenshot.comparators` in the Vitest config and reference its exact key.
3. Check spelling and case of the comparator name against the config keys.

Example fix

// vitest.config.ts
// before: comparator: 'odiff' referenced but not registered

// after
export default defineConfig({
  test: {
    browser: {
      expect: {
        toMatchScreenshot: {
          comparators: { odiff: myOdiffComparator },
        },
      },
    },
  },
})

const BUILTIN = new Set(['pixelmatch'])
const custom = new Set(Object.keys(config.test?.browser?.expect?.toMatchScreenshot?.comparators ?? {}))
if (!BUILTIN.has(name) && !custom.has(name)) {
  throw new Error(`Unknown comparator '${name}'. Built-in: pixelmatch. Registered: ${[...custom].join(', ')}`)
}

When it happens

Trigger: Passing `comparator: 'odiff'` (or any name) without registering it in config; misspelling `'pixelmatch'`; referencing a custom comparator key that was never added to `browser.expect.toMatchScreenshot.comparators`.

Common situations: Copy-pasting a comparator name from docs/another tool (e.g. `odiff`) without installing/registering it; renaming a custom comparator in code but not in config; case mismatch in the key.

Related errors

• 'toMatchScreenshot' cannot be used with "not"
• All browser instances within a project must use the same…
• "browser.instances" was set in the config, but the array is…
• browser is not initialized
• Browser Mode requires the "provider" to always be specified.

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

Appendix: source

Thrown at packages/browser/src/node/commands/screenshotMatcher/comparators/index.ts:34

  context: BrowserCommandContext,
): Comparator<ScreenshotComparatorRegistry[ComparatorName]> {
  if (comparator in comparators) {
    return comparators[comparator]
  }

  const customComparators = context
    .project
    .config
    .browser
    .expect
    ?.toMatchScreenshot
    ?.comparators

  if (customComparators && comparator in customComparators) {
    return customComparators[comparator]
  }

  throw new Error(`Unrecognized comparator ${comparator}`)
}

export type AnyComparator = Comparator<ScreenshotComparatorRegistry[keyof ScreenshotComparatorRegistry]>

View on GitHub (pinned to 1fa9837ec2)