tailwindlabs/tailwindcss · error · Error

Cannot apply unknown utility class `${candidate}`

Error message

Cannot apply unknown utility class `${candidate}`

What it means

The terminal fallback inside `@apply`'s `onInvalidCandidate`. After ruling out prefix mismatch, blocklist, missing variants, and an empty theme, the candidate is genuinely unrecognizable, so this generic 'unknown utility class' error is thrown.

Source

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

                    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.
            if (designSystem.theme.size === 0) {
              throw new Error(
                `Cannot apply unknown utility class \`${candidate}\`. Are you using CSS modules or similar and missing \`@reference\`? https://tailwindcss.com/docs/functions-and-directives#reference-directive`,
              )
            }

            // Fallback to most generic error message
            throw new Error(`Cannot apply unknown utility class \`${candidate}\``)
          },
        })

        let src = child.src

        let candidateAst = compiled.astNodes.map((node) => {
          let candidate = compiled.nodeSorting.get(node)?.candidate
          let candidateOffset = candidate ? candidateOffsets[candidate] : undefined

          node = cloneAstNode(node)

          if (!src || !candidate || candidateOffset === undefined) {
            // While the original nodes may have come from an `@utility` we still
            // want to replace the source because the `@apply` is ultimately the
            // reason the node was emitted into the AST.
            walk([node], (node) => {
              node.src = src
            })

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Register the class as a custom utility with the `@utility` directive if it should be appliable.
2. Correct the candidate name against the Tailwind utility reference for your version.
3. Install/enable the plugin that provides the utility, or write the CSS by hand instead of `@apply`.

Example fix

// before
.card { @apply shadow-card; } /* shadow-card not defined */
// after
@utility shadow-card {
  box-shadow: 0 4px 12px rgba(0,0,0,.1);
}
.card { @apply shadow-card; }

function isKnownUtility(designSystem, candidate) {
  return designSystem.candidatesToCss([candidate])[0] !== null;
}
// if (!isKnownUtility(designSystem, 'btn-primary')) { /* register via @utility */ }

When it happens

Trigger: Applying a class that is not a Tailwind utility and not a custom utility registered via `@utility`, e.g. `@apply btn-primary;` where `btn-primary` is a plain CSS class. Also fires for malformed candidates that survive the earlier checks.

Common situations: Treating a component class as a utility; referencing a utility from a plugin that is not loaded; typo that happens to pass the variant probe; using a utility that only exists in a newer/older Tailwind version.

Related errors

• 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 utility class `${candidate}` because the `${unk
• Cannot apply utility class `${candidate}` because the ${unkn

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