tailwindlabs/tailwindcss · error · Error

Cannot apply utility class `${candidate}` because it has bee

Error message

Cannot apply utility class `${candidate}` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes

What it means

Thrown when a candidate being applied is a member of `designSystem.invalidCandidates`. That set is populated from the JS-config `blocklist` array or from `@source not inline(...)` exclusions, so Tailwind refuses to expand a class the user has explicitly disabled. The message links to the docs on explicitly excluding classes.

Source

Thrown at packages/tailwindcss/src/apply.ts:236

          respectImportant: false,
          onInvalidCandidate: (candidate) => {
            // When using prefix, make sure prefix is used in candidate
            if (designSystem.theme.prefix && !candidate.startsWith(designSystem.theme.prefix)) {
              throw new Error(
                `Cannot apply unprefixed utility class \`${candidate}\`. Did you mean \`${designSystem.theme.prefix}:${candidate}\`?`,
              )
            }

            // When the utility is blocklisted, let the user know
            //
            // Note: `@apply` is processed before handling incoming classes from
            // template files. This means that the `invalidCandidates` set will
            // only contain explicit classes via:
            //
            // - `blocklist` from a JS config
            // - `@source not inline(…)`
            if (designSystem.invalidCandidates.has(candidate)) {
              throw new Error(
                `Cannot apply utility class \`${candidate}\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,
              )
            }

            // Verify if variants exist
            let parts = segment(candidate, ':')
            if (parts.length > 1) {
              let utility = parts.pop()!

              // Ensure utility on its own compiles, if not, we will fallback to
              // the next error
              if (designSystem.candidatesToCss([utility])[0]) {
                let compiledVariants = designSystem.candidatesToCss(
                  parts.map((variant) => `${variant}:[--tw-variant-check:1]`),
                )
                let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)
                if (unknownVariants.length > 0) {
                  if (unknownVariants.length === 1) {

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Remove the class from `blocklist` / `@source not inline(...)` if you need it via `@apply`.
2. Replace the `@apply <disabled-class>` with hand-written CSS that achieves the same effect.
3. Use a different, non-blocklisted utility that produces the same result.

Example fix

// before
// tailwind.config.js: blocklist: ['float-right']
.pull-right { @apply float-right; }
// after
.pull-right { float: right; }

const blocked = new Set(resolvedConfig.blocklist);
function assertNotBlocked(candidates) {
  for (const c of candidates) {
    const base = c.split(':').pop();
    if (blocked.has(base)) throw new Error(`${base} is blocklisted, cannot @apply`);
  }
}
// assertNotBlocked(['hidden']);

When it happens

Trigger: Listing a utility in `blocklist: ['hidden']` (JS config) or adding `@source not inline("hidden");` in CSS, then writing `@apply hidden;` in a component. Fires only inside `@apply`'s `onInvalidCandidate` because `@apply` is processed before template scanning.

Common situations: Disabling a utility project-wide to enforce a design system, then forgetting the ban applies inside `@apply`; migrating from v3 where blocklist behavior was looser.

Related errors

• Cannot apply unprefixed utility class `${candidate}`. Did yo
• The rule `@apply ${list}` must not have a body.
• Cannot apply utility class `${candidate}` because the `${unk
• Cannot apply utility class `${candidate}` because the ${unkn
• Cannot apply unknown utility class `${candidate}`. Are you u

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