{"record":{"id":"9381393fe5a1bf82","repo":"tailwindlabs/tailwindcss","slug":"cannot-apply-utility-class-candidate-because","errorCode":null,"errorMessage":"Cannot apply utility class `${candidate}` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes","messagePattern":"Cannot apply utility class `(.+?)` because it has been explicitly disabled: https://tailwindcss\\.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/apply.ts","lineNumber":236,"sourceCode":"          respectImportant: false,\n          onInvalidCandidate: (candidate) => {\n            // When using prefix, make sure prefix is used in candidate\n            if (designSystem.theme.prefix && !candidate.startsWith(designSystem.theme.prefix)) {\n              throw new Error(\n                `Cannot apply unprefixed utility class \\`${candidate}\\`. Did you mean \\`${designSystem.theme.prefix}:${candidate}\\`?`,\n              )\n            }\n\n            // When the utility is blocklisted, let the user know\n            //\n            // Note: `@apply` is processed before handling incoming classes from\n            // template files. This means that the `invalidCandidates` set will\n            // only contain explicit classes via:\n            //\n            // - `blocklist` from a JS config\n            // - `@source not inline(…)`\n            if (designSystem.invalidCandidates.has(candidate)) {\n              throw new Error(\n                `Cannot apply utility class \\`${candidate}\\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,\n              )\n            }\n\n            // Verify if variants exist\n            let parts = segment(candidate, ':')\n            if (parts.length > 1) {\n              let utility = parts.pop()!\n\n              // Ensure utility on its own compiles, if not, we will fallback to\n              // the next error\n              if (designSystem.candidatesToCss([utility])[0]) {\n                let compiledVariants = designSystem.candidatesToCss(\n                  parts.map((variant) => `${variant}:[--tw-variant-check:1]`),\n                )\n                let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)\n                if (unknownVariants.length > 0) {\n                  if (unknownVariants.length === 1) {","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/apply.ts#L218-L254","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the class from `blocklist` / `@source not inline(...)` if you need it via `@apply`.","Replace the `@apply <disabled-class>` with hand-written CSS that achieves the same effect.","Use a different, non-blocklisted utility that produces the same result."],"exampleFix":"// before\n// tailwind.config.js: blocklist: ['float-right']\n.pull-right { @apply float-right; }\n// after\n.pull-right { float: right; }","handlingStrategy":"validation","validationCode":"const blocked = new Set(resolvedConfig.blocklist);\nfunction assertNotBlocked(candidates) {\n  for (const c of candidates) {\n    const base = c.split(':').pop();\n    if (blocked.has(base)) throw new Error(`${base} is blocklisted, cannot @apply`);\n  }\n}\n// assertNotBlocked(['hidden']);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep a project-level list of blocklisted utilities and grep `@apply` usages against it in CI.","Prefer hand-written CSS over `@apply` for utilities you have intentionally disabled."],"tags":["tailwind","apply","blocklist","config"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}