tailwindlabs/tailwindcss · error · Error

Cannot apply utility class `${candidate}` because the `${unk

Error message

Cannot apply utility class `${candidate}` because the `${unknownVariants[0]}` variant does not exist.

What it means

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.

Source

Thrown at packages/tailwindcss/src/apply.ts:255

                `Cannot apply utility class \`${candidate}\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,
              )
            }

            // Verify if variants exist
            let parts = segment(candidate, ':')
            if (parts.length > 1) {
              let utility = parts.pop()!

              // Ensure utility on its own compiles, if not, we will fallback to
              // the next error
              if (designSystem.candidatesToCss([utility])[0]) {
                let compiledVariants = designSystem.candidatesToCss(
                  parts.map((variant) => `${variant}:[--tw-variant-check:1]`),
                )
                let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)
                if (unknownVariants.length > 0) {
                  if (unknownVariants.length === 1) {
                    throw new Error(
                      `Cannot apply utility class \`${candidate}\` because the ${unknownVariants.map((variant) => `\`${variant}\``)} variant does not exist.`,
                    )
                  } else {
                    let formatter = new Intl.ListFormat('en', {
                      style: 'long',
                      type: 'conjunction',
                    })
                    throw new Error(
                      `Cannot apply utility class \`${candidate}\` because the ${formatter.format(unknownVariants.map((variant) => `\`${variant}\``))} variants do not exist.`,
                    )
                  }
                }
              }
            }

            // When the theme is empty, it means that no theme was loaded and
            // `@import "tailwindcss"`, `@reference "app.css"` or similar is
            // very likely missing.

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Correct the variant spelling (e.g. `hovar:` → `hover:`).
2. Install/enable the plugin or `addVariant` call that registers the variant.
3. Drop the variant and apply the utility without it if it is not essential.

Example fix

// before
.badge { @apply hovar:bg-blue-500; }
// after
.badge { @apply hover:bg-blue-500; }

function variantsExist(designSystem, candidate) {
  const parts = candidate.split(':');
  if (parts.length < 2) return true;
  const util = parts.pop();
  if (!designSystem.candidatesToCss([util])[0]) return false;
  const probes = designSystem.candidatesToCss(parts.map(v => `${v}:[--tw-variant-check:1]`));
  return probes.every(Boolean);
}
// variantsExist(designSystem, 'hover:bg-red-500');

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

• Cannot apply utility class `${candidate}` because the ${unkn
• The rule `@apply ${list}` must not have a body.
• Cannot apply unprefixed utility class `${candidate}`. Did yo
• Cannot apply utility class `${candidate}` because it has bee
• Cannot apply unknown utility class `${candidate}`. Are you u

AI-assisted analysis of tailwindlabs/tailwindcss@16e94cbf7f (2026-08-12). Data as JSON: /api/errors/62da203d5bb331bd. Report an issue: GitHub.