{"id":"26fb1a45ae023e6e","repo":"vitest-dev/vitest","slug":"unrecognized-comparator-comparator","errorCode":null,"errorMessage":"Unrecognized comparator ${comparator}","messagePattern":"Unrecognized comparator (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/node/commands/screenshotMatcher/comparators/index.ts","lineNumber":34,"sourceCode":"  context: BrowserCommandContext,\n): Comparator<ScreenshotComparatorRegistry[ComparatorName]> {\n  if (comparator in comparators) {\n    return comparators[comparator]\n  }\n\n  const customComparators = context\n    .project\n    .config\n    .browser\n    .expect\n    ?.toMatchScreenshot\n    ?.comparators\n\n  if (customComparators && comparator in customComparators) {\n    return customComparators[comparator]\n  }\n\n  throw new Error(`Unrecognized comparator ${comparator}`)\n}\n\nexport type AnyComparator = Comparator<ScreenshotComparatorRegistry[keyof ScreenshotComparatorRegistry]>\n","sourceCodeStart":16,"sourceCodeEnd":38,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/node/commands/screenshotMatcher/comparators/index.ts#L16-L38","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the built-in `'pixelmatch'` comparator (default).","Register your custom comparator under the exact name you reference: `test.browser.expect.toMatchScreenshot.comparators = { odiff: myComparator }`.","Verify the spelling/casing of the comparator name in both config and any baseline metadata."],"exampleFix":"// vitest.config.ts\n// before: comparator 'odiff' referenced but not registered\n\n// after\nexport default defineConfig({\n  test: {\n    browser: {\n      expect: { toMatchScreenshot: { comparators: { odiff: myOdiffComparator } } },\n    },\n  },\n})","handlingStrategy":"validation","validationCode":"const BUILTIN = new Set(['pixelmatch'])\nfunction isRegisteredComparator(name: string, custom: Record<string, unknown> | undefined): boolean {\n  return BUILTIN.has(name) || !!custom && name in custom\n}\nif (!isRegisteredComparator(name, configuredComparators)) throw new Error(`unknown comparator ${name}`)","typeGuard":"function isKnownComparator(name: string, custom: Record<string, unknown> | undefined): boolean {\n  return name === 'pixelmatch' || (!!custom && name in custom)\n}","tryCatchPattern":null,"preventionTips":["Default to the built-in 'pixelmatch' comparator.","Register custom comparators under the exact name you reference.","Keep comparator config and baseline metadata in sync when renaming."],"tags":["browser","screenshot","comparator","tomatchscreenshot","configuration","pixelmatch"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}