Tailwind "Cannot apply unknown utility class" - Fix @apply in CI

A Tailwind @apply referenced a utility class Tailwind does not recognize. The class is misspelled, it is a custom/component class rather than a utility, or it depends on config (a theme value or plugin) the build does not have.

What this error means

The CSS build fails with Cannot apply unknown utility class: <class> (older versions: The <class> class does not exist). It names the offending class and the stylesheet.

CssSyntaxError: Cannot apply unknown utility class: bg-brand-primary
  > 4 |   @apply bg-brand-primary text-white;
      |          ^

Common causes

Typo or non-utility class in @apply

@apply only accepts Tailwind utility classes. A misspelling, or applying a custom component class, makes Tailwind treat it as unknown.

Class depends on config the build lacks

A class like bg-brand-primary requires a theme.extend.colors.brand entry (or a plugin). If the config is missing that value, the utility is never generated.

How to fix it

Define the value in the Tailwind config

Add the theme value (or plugin) that generates the utility you apply.

// tailwind.config.js
module.exports = {
  theme: { extend: { colors: { brand: { primary: '#4f46e5' } } } },
}

Apply only real utility classes

1. Confirm the class spelling against Tailwind's generated utilities.
2. For custom classes, define them with @layer components and reference real utilities inside.
3. Do not @apply another component class - @apply is for utilities.

How to prevent it

• Add custom theme values/plugins before @applying the classes they generate.
• Keep one tailwind.config.js that the build actually loads.
• Build CSS in CI so unknown-class errors fail before deploy.

Related guides