vitest-dev/vitest · error · Error

Unrecognized comparator ${comparator}

Error message

Unrecognized comparator ${comparator}

What it means

Thrown by `getComparator` at comparators/index.ts:33-34 when the requested comparator name is neither a built-in (`pixelmatch`) nor a key in the user's custom comparators registered via `browser.expect.toMatchScreenshot.comparators`. The comparator is what diffs two decoded images and produces pass/fail + diff image.

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

Solutions

1. Use the built-in `'pixelmatch'` comparator (default).
2. Register your custom comparator under the exact name you reference: `test.browser.expect.toMatchScreenshot.comparators = { odiff: myComparator }`.
3. Verify the spelling/casing of the comparator name in both config and any baseline metadata.

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'])
function isRegisteredComparator(name: string, custom: Record<string, unknown> | undefined): boolean {
  return BUILTIN.has(name) || !!custom && name in custom
}
if (!isRegisteredComparator(name, configuredComparators)) throw new Error(`unknown comparator ${name}`)

function isKnownComparator(name: string, custom: Record<string, unknown> | undefined): boolean {
  return name === 'pixelmatch' || (!!custom && name in custom)
}

When it happens

Trigger: Setting `options.comparatorName` (or a baseline's metadata) to a name that wasn't registered, e.g. `'odiff'` without registering it. Referencing a custom comparator by a misspelled name. Removing a custom comparator from config but keeping baselines that reference it.

Common situations: Migrating from another visual-regression tool (e.g. odiff) and assuming Vitest bundles it. Typos in comparator config keys. Config-driven comparator selection where the config was edited but the implementation not added.

Related errors

• No codec found for type ${type}
• Cannot take a screenshot without a test path
• Cannot take a screenshot outside of a test.
• Cannot take a screenshot in a concurrent test because concur
• 'toMatchScreenshot' cannot be used with "not"

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