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

An @apply named a utility Tailwind cannot produce - a typo, a class gated behind a disabled core plugin, or a custom utility that is not defined. Tailwind refuses to apply what it cannot generate.

What this error means

The build fails with Cannot apply unknown utility class: <name> pointing at the @apply line in your CSS.

node

Error: Cannot apply unknown utility class: bg-brand-primary

  at /app/src/styles/components.css:12:3
  @apply bg-brand-primary text-white;

Common causes

Custom color/utility not in config

You @apply bg-brand-primary, but brand.primary is not defined under theme.extend.colors.

Typo or disabled core plugin

The class is misspelled, or the core plugin that generates it was disabled in config.

How to fix it

Define the custom utility in config

Add the color/utility under theme.extend so Tailwind can generate it.

tailwind.config.js

// tailwind.config.js
module.exports = {
  theme: { extend: { colors: { brand: { primary: '#0b5fff' } } } },
};

Use a literal value instead of @apply

When the value is one-off, write the declaration directly rather than applying a non-existent utility.

components.css

.btn { background-color: theme('colors.brand.primary'); color: #fff; }

How to prevent it

Keep design tokens defined in the Tailwind config before referencing them.
Build CSS locally before pushing so unknown-utility errors surface early.