{"record":{"id":"be0b17a90bbe3614","repo":"tailwindlabs/tailwindcss","slug":"cannot-apply-unknown-utility-class-candidate","errorCode":null,"errorMessage":"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","messagePattern":"Cannot apply unknown utility class `(.+?)`\\. Are you using CSS modules or similar and missing `@reference`\\? https://tailwindcss\\.com/docs/functions-and-directives#reference-directive","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/apply.ts","lineNumber":275,"sourceCode":"                    )\n                  } else {\n                    let formatter = new Intl.ListFormat('en', {\n                      style: 'long',\n                      type: 'conjunction',\n                    })\n                    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) {","sourceCodeStart":257,"sourceCodeEnd":293,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/apply.ts#L257-L293","documentation":"Thrown as the first fallback when a candidate fails to compile AND `designSystem.theme.size === 0`. An empty theme means no `@import \"tailwindcss\"` / `@reference` has loaded theme tokens into the current stylesheet context — the classic CSS-modules / isolated-CSS-file scenario. The message points at the `@reference` directive docs.","triggerScenarios":"Using `@apply` inside a CSS Module or a standalone `.css` file that does not import Tailwind's theme. Because the file is processed in isolation, `designSystem.theme` is empty, so every candidate is 'unknown'. Fires after the prefix/blocklist/variant checks have all passed.","commonSituations":"Vue/Next.js CSS Modules that `@apply` utilities without first importing the theme; splitting component CSS into files that are compiled independently; removing a top-level `@import \"tailwindcss\"` during refactor.","solutions":["Add `@reference \"tailwindcss\";` (or `@reference \"../app.css\";`) at the top of the isolated CSS file so the theme is available.","Move the `@apply` usage into a file that already imports Tailwind.","Ensure the main entry actually imports `@import \"tailwindcss\";` so the design system is populated."],"exampleFix":"// before (Button.module.css)\n.btn { @apply px-4 py-2; }\n// after\n@reference \"tailwindcss\";\n.btn { @apply px-4 py-2; }","handlingStrategy":"validation","validationCode":"function ensureThemeLoaded(designSystem) {\n  if (designSystem.theme.size === 0) {\n    throw new Error('Theme empty — add @reference \"tailwindcss\"; to this file');\n  }\n}\n// ensureThemeLoaded(designSystem);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always add `@reference \"tailwindcss\";` (or your main CSS entry) at the top of CSS Modules that use `@apply`.","Audit isolated CSS files during onboarding to confirm each has theme access."],"tags":["tailwind","apply","css-modules","reference","theme"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}