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

By Kaveh Alemi·Latchkey

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.

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

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

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

Use a literal value instead of @apply

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

.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.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation