{"record":{"id":"62da203d5bb331bd","repo":"tailwindlabs/tailwindcss","slug":"cannot-apply-utility-class-candidate-because-62da20","errorCode":null,"errorMessage":"Cannot apply utility class `${candidate}` because the `${unknownVariants[0]}` variant does not exist.","messagePattern":"Cannot apply utility class `(.+?)` because the `(.+?)` variant does not exist\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/apply.ts","lineNumber":255,"sourceCode":"                `Cannot apply utility class \\`${candidate}\\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,\n              )\n            }\n\n            // Verify if variants exist\n            let parts = segment(candidate, ':')\n            if (parts.length > 1) {\n              let utility = parts.pop()!\n\n              // Ensure utility on its own compiles, if not, we will fallback to\n              // the next error\n              if (designSystem.candidatesToCss([utility])[0]) {\n                let compiledVariants = designSystem.candidatesToCss(\n                  parts.map((variant) => `${variant}:[--tw-variant-check:1]`),\n                )\n                let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)\n                if (unknownVariants.length > 0) {\n                  if (unknownVariants.length === 1) {\n                    throw new Error(\n                      `Cannot apply utility class \\`${candidate}\\` because the ${unknownVariants.map((variant) => `\\`${variant}\\``)} variant does not exist.`,\n                    )\n                  } else {\n                    let formatter = new Intl.ListFormat('en', {\n                      style: 'long',\n                      type: 'conjunction',\n                    })\n                    throw new Error(\n                      `Cannot apply utility class \\`${candidate}\\` because the ${formatter.format(unknownVariants.map((variant) => `\\`${variant}\\``))} variants do not exist.`,\n                    )\n                  }\n                }\n              }\n            }\n\n            // When the theme is empty, it means that no theme was loaded and\n            // `@import \"tailwindcss\"`, `@reference \"app.css\"` or similar is\n            // very likely missing.","sourceCodeStart":237,"sourceCodeEnd":273,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/apply.ts#L237-L273","documentation":"Thrown inside `@apply` candidate validation when the candidate has exactly one variant segment that fails to compile. The base utility compiles on its own, but when Tailwind probes each variant with `[--tw-variant-check:1]`, the single variant resolves to `null`. The message names the missing variant in backticks.","triggerScenarios":"Writing `@apply hovar:focus` (typo), `@apply 2xl:text-center` (variant not registered), or a custom variant name that was never defined via `addVariant`. Fires only when `parts.length > 1`, the leaf utility compiles, and exactly one variant produces `null`.","commonSituations":"Typo in a variant name; using a variant from a plugin that isn't installed; assuming a custom variant exists after a framework upgrade that renamed it.","solutions":["Correct the variant spelling (e.g. `hovar:` → `hover:`).","Install/enable the plugin or `addVariant` call that registers the variant.","Drop the variant and apply the utility without it if it is not essential."],"exampleFix":"// before\n.badge { @apply hovar:bg-blue-500; }\n// after\n.badge { @apply hover:bg-blue-500; }","handlingStrategy":"validation","validationCode":"function variantsExist(designSystem, candidate) {\n  const parts = candidate.split(':');\n  if (parts.length < 2) return true;\n  const util = parts.pop();\n  if (!designSystem.candidatesToCss([util])[0]) return false;\n  const probes = designSystem.candidatesToCss(parts.map(v => `${v}:[--tw-variant-check:1]`));\n  return probes.every(Boolean);\n}\n// variantsExist(designSystem, 'hover:bg-red-500');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Maintain a list of registered variant names and check `@apply` candidates against it before build.","Run the Tailwind CLI in watch mode locally so variant typos surface immediately."],"tags":["tailwind","apply","variant","typo"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}