tailwindlabs/tailwindcss · error · Error

Cannot apply unknown utility class

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.

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

• Cannot apply unknown utility class
• Cannot apply unprefixed utility class
• Cannot apply utility class
• Cannot apply utility class
• Cannot apply utility class

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

Appendix: 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)