{"record":{"id":"6ebd9e70d6811cc9","repo":"tailwindlabs/tailwindcss","slug":"cannot-apply-unprefixed-utility-class-candidate","errorCode":null,"errorMessage":"Cannot apply unprefixed utility class `${candidate}`. Did you mean `${designSystem.theme.prefix}:${candidate}`?","messagePattern":"Cannot apply unprefixed utility class `(.+?)`\\. Did you mean `(.+?):(.+?)`\\?","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/apply.ts","lineNumber":222,"sourceCode":"      let hasBody = child.nodes.length > 0\n\n      if (hasBody && normalIdents.length) {\n        let list = normalIdents.join(' ')\n\n        throw new Error(`The rule \\`@apply ${list}\\` must not have a body.`)\n      }\n\n      // Replace the `@apply` rule with the actual utility classes\n      {\n        // Parse the candidates to an AST that we can replace the `@apply` rule\n        // with.\n        let candidates = Object.keys(candidateOffsets)\n        let compiled = compileCandidates(candidates, designSystem, {\n          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","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/apply.ts#L204-L240","documentation":"Thrown during candidate compilation inside `@apply` when a `prefix` is configured on the design system theme but the candidate being applied does not start with that prefix. Tailwind requires prefixed utilities everywhere (including `@apply`) so the candidate is rejected and the user is told the likely intended prefixed form.","triggerScenarios":"Configuring `prefix: 'tw'` (via CSS `@import` prefix option or JS config) and then writing `@apply flex;` instead of `@apply tw:flex;`. Fires in `onInvalidCandidate` only when `designSystem.theme.prefix` is truthy and `!candidate.startsWith(prefix)`.","commonSituations":"Setting a prefix for design-system isolation and forgetting it inside component CSS; copy-pasting utility classes from a non-prefixed project into a prefixed one.","solutions":["Prefix the utility in the `@apply`: change `@apply flex` to `@apply tw:flex` (using your configured prefix).","If you do not actually want a prefix, remove the `prefix` configuration from your `@import \"tailwindcss\"` options or JS config.","Use the suggested `${prefix}:${candidate}` form printed in the error message verbatim."],"exampleFix":"// before\n@import \"tailwindcss\" prefix(tw);\n.btn { @apply flex; }\n// after\n@import \"tailwindcss\" prefix(tw);\n.btn { @apply tw:flex; }","handlingStrategy":"validation","validationCode":"const prefix = designSystem.theme.prefix;\nfunction assertPrefixed(candidates) {\n  if (!prefix) return;\n  for (const c of candidates) {\n    if (!c.startsWith(prefix + ':') && !c.startsWith(prefix)) {\n      throw new Error(`Candidate ${c} missing prefix ${prefix}`);\n    }\n  }\n}\n// assertPrefixed(['tw:flex']);","typeGuard":null,"tryCatchPattern":"try { designSystem.compileAst(nodes) } catch (e) {\n  if (/unprefixed utility class/.test(e.message)) { /* suggest prefix */ }\n  else throw e;\n}","preventionTips":["When introducing a prefix, search-and-replace all `@apply` sites to add it.","Document the configured prefix at the top of every CSS file."],"tags":["tailwind","apply","prefix","config"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}