{"record":{"id":"0ceda67346aa7275","repo":"tailwindlabs/tailwindcss","slug":"cannot-use-variant-with-unknown-variant-vari","errorCode":null,"errorMessage":"Cannot use `@variant` with unknown variant: ${variant}","messagePattern":"Cannot use `@variant` with unknown variant: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/variants.ts","lineNumber":1305,"sourceCode":"      // nodes for sourcemap `dst` location information.\n      let node = styleRule(\n        '&',\n        idx === compoundVariants.length - 1\n          ? variantNode.nodes\n          : variantNode.nodes.map(cloneAstNode),\n      )\n\n      let stackedVariants = segment(compoundVariant, ':')\n      for (let i = stackedVariants.length - 1; i >= 0; --i) {\n        let variant = stackedVariants[i].trim()\n\n        if (!variant) {\n          throw new Error(`Cannot use \\`@variant\\` with empty variant`)\n        }\n\n        let variantAst = designSystem.parseVariant(variant)\n        if (variantAst === null) {\n          throw new Error(`Cannot use \\`@variant\\` with unknown variant: ${variant}`)\n        }\n\n        let result = applyVariant(node, variantAst, designSystem.variants)\n        if (result === null) {\n          throw new Error(`Cannot use \\`@variant\\` with variant: ${variant}`)\n        }\n      }\n\n      if (node.selector === '&') {\n        nodes.push(...node.nodes)\n      } else {\n        nodes.push(node)\n      }\n    }\n\n    // Update the variant at-rule node, to be the `&` rule node\n    features |= Features.Variants\n    return WalkAction.Replace(nodes)","sourceCodeStart":1287,"sourceCodeEnd":1323,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/variants.ts#L1287-L1323","documentation":"Thrown by substituteAtVariant() when designSystem.parseVariant(variant) returns null, meaning the variant name is not registered in the design system. Every segment of a colon-separated variant stack must resolve to a known variant (hover, focus, md, dark, custom-variant, etc.). This fires after the empty-variant check, so the name is non-empty but unrecognized.","triggerScenarios":"Using '@variant foo { ... }' where 'foo' is neither a built-in variant nor a custom variant registered via @custom-variant. Referencing a variant before it is defined, or misspelling one (e.g. 'hvoer').","commonSituations":"Forgetting to declare a custom variant with @custom-variant before using it in @variant. Typos in variant names. Assuming a plugin-registered variant is available when the plugin isn't loaded. Ordering issue where @variant appears before the @custom-variant definition in source order.","solutions":["Register the variant first: '@custom-variant foo (&:is(.foo));' then use '@variant foo'.","Fix the typo: 'hvoer' -> 'hover'.","Confirm the variant is available (built-in or from a loaded plugin) in your Tailwind version."],"exampleFix":"/* before — throws if 'tag' is undefined */\n@variant tag {\n  .x { display: none; }\n}\n\n/* after */\n@custom-variant tag (&:is([data-tag]));\n@variant tag {\n  .x { display: none; }\n}","handlingStrategy":"validation","validationCode":"// Check a variant resolves before authoring @variant\nconst known = new Set(['hover','focus','active','md','lg','dark', /* ... */])\nfunction variantExists(name: string): boolean {\n  return known.has(name) || customVariants.has(name)\n}\nif (!variantExists(name)) {\n  throw new Error(`Unknown variant '${name}' — register via @custom-variant`)\n}","typeGuard":"function isKnownVariant(name: string, designSystem: DesignSystem): boolean {\n  return designSystem.parseVariant(name) !== null\n}","tryCatchPattern":null,"preventionTips":["Register custom variants with @custom-variant before referencing them.","Define @custom-variant earlier in source order than its @variant uses.","Double-check variant spelling against the built-in list."],"tags":["tailwindcss","variant","css","v4","configuration"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}