tailwindlabs/tailwindcss · error · Error

Cannot apply unknown utility class `${candidate}`. Are you u

Error message

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

What it means

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.

Source

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

                    )
                  } else {
                    let formatter = new Intl.ListFormat('en', {
                      style: 'long',
                      type: 'conjunction',
                    })
                    throw new Error(
                      `Cannot apply utility class \`${candidate}\` because the ${formatter.format(unknownVariants.map((variant) => `\`${variant}\``))} variants do not exist.`,
                    )
                  }
                }
              }
            }

            // When the theme is empty, it means that no theme was loaded and
            // `@import "tailwindcss"`, `@reference "app.css"` or similar is
            // very likely missing.
            if (designSystem.theme.size === 0) {
              throw new Error(
                `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`,
              )
            }

            // Fallback to most generic error message
            throw new Error(`Cannot apply unknown utility class \`${candidate}\``)
          },
        })

        let src = child.src

        let candidateAst = compiled.astNodes.map((node) => {
          let candidate = compiled.nodeSorting.get(node)?.candidate
          let candidateOffset = candidate ? candidateOffsets[candidate] : undefined

          node = cloneAstNode(node)

          if (!src || !candidate || candidateOffset === undefined) {

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Add `@reference "tailwindcss";` (or `@reference "../app.css";`) at the top of the isolated CSS file so the theme is available.
2. Move the `@apply` usage into a file that already imports Tailwind.
3. Ensure the main entry actually imports `@import "tailwindcss";` so the design system is populated.

Example fix

// before (Button.module.css)
.btn { @apply px-4 py-2; }
// after
@reference "tailwindcss";
.btn { @apply px-4 py-2; }

function ensureThemeLoaded(designSystem) {
  if (designSystem.theme.size === 0) {
    throw new Error('Theme empty — add @reference "tailwindcss"; to this file');
  }
}
// ensureThemeLoaded(designSystem);

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The rule `@apply ${list}` must not have a body.
• Cannot apply unprefixed utility class `${candidate}`. Did yo
• Cannot apply utility class `${candidate}` because it has bee
• Cannot apply utility class `${candidate}` because the `${unk
• Cannot apply utility class `${candidate}` because the ${unkn

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