{"record":{"id":"c1a7159e75b6cc1b","repo":"tailwindlabs/tailwindcss","slug":"cannot-apply-unknown-utility-class-candidate-c1a715","errorCode":null,"errorMessage":"Cannot apply unknown utility class `${candidate}`","messagePattern":"Cannot apply unknown utility class `(.+?)`","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/apply.ts","lineNumber":281,"sourceCode":"                    throw new Error(\n                      `Cannot apply utility class \\`${candidate}\\` because the ${formatter.format(unknownVariants.map((variant) => `\\`${variant}\\``))} variants do not exist.`,\n                    )\n                  }\n                }\n              }\n            }\n\n            // When the theme is empty, it means that no theme was loaded and\n            // `@import \"tailwindcss\"`, `@reference \"app.css\"` or similar is\n            // very likely missing.\n            if (designSystem.theme.size === 0) {\n              throw new Error(\n                `Cannot apply unknown utility class \\`${candidate}\\`. Are you using CSS modules or similar and missing \\`@reference\\`? https://tailwindcss.com/docs/functions-and-directives#reference-directive`,\n              )\n            }\n\n            // Fallback to most generic error message\n            throw new Error(`Cannot apply unknown utility class \\`${candidate}\\``)\n          },\n        })\n\n        let src = child.src\n\n        let candidateAst = compiled.astNodes.map((node) => {\n          let candidate = compiled.nodeSorting.get(node)?.candidate\n          let candidateOffset = candidate ? candidateOffsets[candidate] : undefined\n\n          node = cloneAstNode(node)\n\n          if (!src || !candidate || candidateOffset === undefined) {\n            // While the original nodes may have come from an `@utility` we still\n            // want to replace the source because the `@apply` is ultimately the\n            // reason the node was emitted into the AST.\n            walk([node], (node) => {\n              node.src = src\n            })","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/apply.ts#L263-L299","documentation":"The terminal fallback inside `@apply`'s `onInvalidCandidate`. After ruling out prefix mismatch, blocklist, missing variants, and an empty theme, the candidate is genuinely unrecognizable, so this generic 'unknown utility class' error is thrown.","triggerScenarios":"Applying a class that is not a Tailwind utility and not a custom utility registered via `@utility`, e.g. `@apply btn-primary;` where `btn-primary` is a plain CSS class. Also fires for malformed candidates that survive the earlier checks.","commonSituations":"Treating a component class as a utility; referencing a utility from a plugin that is not loaded; typo that happens to pass the variant probe; using a utility that only exists in a newer/older Tailwind version.","solutions":["Register the class as a custom utility with the `@utility` directive if it should be appliable.","Correct the candidate name against the Tailwind utility reference for your version.","Install/enable the plugin that provides the utility, or write the CSS by hand instead of `@apply`."],"exampleFix":"// before\n.card { @apply shadow-card; } /* shadow-card not defined */\n// after\n@utility shadow-card {\n  box-shadow: 0 4px 12px rgba(0,0,0,.1);\n}\n.card { @apply shadow-card; }","handlingStrategy":"validation","validationCode":"function isKnownUtility(designSystem, candidate) {\n  return designSystem.candidatesToCss([candidate])[0] !== null;\n}\n// if (!isKnownUtility(designSystem, 'btn-primary')) { /* register via @utility */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Register custom appliable classes with `@utility` rather than plain `.class { }`.","Cross-check candidate names against the Tailwind docs for your version before using `@apply`."],"tags":["tailwind","apply","unknown-utility","custom-utility"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}