From 0e789f3f83f78e52b795080d0a0d783e32768a4f Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 16 May 2025 13:41:48 +0200
Subject: [PATCH 01/11] improve `@apply` error messages

---
 packages/tailwindcss/src/apply.ts | 49 ++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/packages/tailwindcss/src/apply.ts b/packages/tailwindcss/src/apply.ts
index 87361804f7ae..b587ff5de82c 100644
--- a/packages/tailwindcss/src/apply.ts
+++ b/packages/tailwindcss/src/apply.ts
@@ -176,7 +176,54 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
         let candidates = Object.keys(candidateOffsets)
         let compiled = compileCandidates(candidates, designSystem, {
           onInvalidCandidate: (candidate) => {
-            throw new Error(`Cannot apply unknown utility class: ${candidate}`)
+            // When using prefix, make sure prefix is used in candidate
+            if (designSystem.theme.prefix && !candidate.startsWith(designSystem.theme.prefix)) {
+              throw new Error(
+                `Cannot apply unprefixed utility class: \`${candidate}\`, did you mean \`${designSystem.theme.prefix}:${candidate}\`?`,
+              )
+            }
+
+            // When the utility is blocklisted, let the user know
+            //
+            // Note: `@apply` is processed before handling incoming classes from
+            // template files. This means that the `invalidCandidates` set will
+            // only contain explicit classes via:
+            //
+            // - `blocklist` from a JS config
+            // - `@source not inline(…)`
+            if (designSystem.invalidCandidates.has(candidate)) {
+              throw new Error(
+                `Cannot apply \`${candidate}\`, it seems like the utility was explicitly excluded and cannot be applied.\n\nMore info: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,
+              )
+            }
+
+            // Verify `@tailwind utilities` or `@reference` is used
+            let hasUtilitiesOrReference = false
+            walk(ast, (node, { context }) => {
+              // Find `@reference`
+              if (context.reference) {
+                hasUtilitiesOrReference = true
+                return WalkAction.Stop
+              }
+
+              // Find `@tailwind utilities`
+              else if (
+                node.kind === 'at-rule' &&
+                node.name === '@tailwind' &&
+                (node.params === 'utilities' || node.params.startsWith('utilities'))
+              ) {
+                hasUtilitiesOrReference = true
+                return WalkAction.Stop
+              }
+            })
+            if (!hasUtilitiesOrReference) {
+              throw new Error(
+                `Cannot apply unknown utility class: \`${candidate}\`.\nIt looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\``,
+              )
+            }
+
+            // Fallback to most generic error message
+            throw new Error(`Cannot apply unknown utility class: \`${candidate}\``)
           },
         })
 

From f9d13b7a589eb15e0f1148cbe5fef193ebe3d866 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 16 May 2025 13:42:17 +0200
Subject: [PATCH 02/11] add and update tests

---
 .../tailwindcss/src/compat/config.test.ts     |  9 +-
 packages/tailwindcss/src/index.test.ts        | 89 ++++++++++++++++++-
 packages/tailwindcss/src/prefix.test.ts       |  2 +-
 3 files changed, 95 insertions(+), 5 deletions(-)

diff --git a/packages/tailwindcss/src/compat/config.test.ts b/packages/tailwindcss/src/compat/config.test.ts
index ea64fe3a1239..b28950dc28bd 100644
--- a/packages/tailwindcss/src/compat/config.test.ts
+++ b/packages/tailwindcss/src/compat/config.test.ts
@@ -1223,6 +1223,7 @@ test('utilities used in @apply must be prefixed', async () => {
   await expect(
     compile(
       css`
+        @tailwind utilities;
         @config "./config.js";
 
         .my-underline {
@@ -1238,7 +1239,7 @@ test('utilities used in @apply must be prefixed', async () => {
       },
     ),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `[Error: Cannot apply unknown utility class: underline]`,
+    `[Error: Cannot apply unprefixed utility class: \`underline\`, did you mean \`tw:underline\`?]`,
   )
 })
 
@@ -1440,7 +1441,11 @@ test('blocklisted candidates cannot be used with `@apply`', async () => {
       },
     ),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `[Error: Cannot apply unknown utility class: bg-white]`,
+    `
+    [Error: Cannot apply \`bg-white\`, it seems like the utility was explicitly excluded and cannot be applied.
+
+    More info: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes]
+  `,
   )
 })
 
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 9c6df63fc3f6..0b9a5d5433e3 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -286,6 +286,91 @@ describe('@apply', () => {
     )
   })
 
+  it('@apply referencing theme values without `@tailwind utilities` or `@reference` should error', () => {
+    return expect(() =>
+      compileCss(css`
+        .foo {
+          @apply p-2;
+        }
+      `),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `
+      [Error: Cannot apply unknown utility class: \`p-2\`.
+      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
+    `,
+    )
+  })
+
+  it('@apply referencing theme values with `@tailwind utilities` should work', async () => {
+    return expect(
+      await compileCss(
+        css`
+          @import 'tailwindcss';
+
+          .foo {
+            @apply p-2;
+          }
+        `,
+        [],
+        {
+          async loadStylesheet() {
+            return {
+              path: '',
+              base: '/',
+              content: css`
+                @theme {
+                  --spacing: 0.25rem;
+                }
+                @tailwind utilities;
+              `,
+            }
+          },
+        },
+      ),
+    ).toMatchInlineSnapshot(`
+      ":root, :host {
+        --spacing: .25rem;
+      }
+
+      .foo {
+        padding: calc(var(--spacing) * 2);
+      }"
+    `)
+  })
+
+  it('@apply referencing theme values with `@reference` should work', async () => {
+    return expect(
+      await compileCss(
+        css`
+          @reference "style.css";
+
+          .foo {
+            @apply p-2;
+          }
+        `,
+        [],
+        {
+          async loadStylesheet() {
+            return {
+              path: '',
+              base: '/',
+              content: css`
+                @theme {
+                  --spacing: 0.25rem;
+                }
+                @tailwind utilities;
+              `,
+            }
+          },
+        },
+      ),
+    ).toMatchInlineSnapshot(`
+      ".foo {
+        padding: calc(var(--spacing, .25rem) * 2);
+      }"
+    `)
+  })
+
   it('should replace @apply with the correct result', async () => {
     expect(
       await compileCss(css`
@@ -466,7 +551,7 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: Cannot apply unknown utility class: bg-not-found]`,
+      `[Error: Cannot apply unknown utility class: \`bg-not-found\`]`,
     )
   })
 
@@ -480,7 +565,7 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: Cannot apply unknown utility class: hocus:bg-red-500]`,
+      `[Error: Cannot apply unknown utility class: \`hocus:bg-red-500\`]`,
     )
   })
 
diff --git a/packages/tailwindcss/src/prefix.test.ts b/packages/tailwindcss/src/prefix.test.ts
index de426ab459fa..32725f21074e 100644
--- a/packages/tailwindcss/src/prefix.test.ts
+++ b/packages/tailwindcss/src/prefix.test.ts
@@ -89,7 +89,7 @@ test('utilities used in @apply must be prefixed', async () => {
       }
     `),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `[Error: Cannot apply unknown utility class: underline]`,
+    `[Error: Cannot apply unprefixed utility class: \`underline\`, did you mean \`tw:underline\`?]`,
   )
 })
 

From 16d4ea5d011ca7e94922345cc565e00eb4124faa Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 16 May 2025 13:42:26 +0200
Subject: [PATCH 03/11] delay making `@tailwind utilities` a context node

If we do this _before_ handling `@apply`, then we won't be able to find
a `@tailwind utilities` at-rule.
---
 packages/tailwindcss/src/index.ts | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/tailwindcss/src/index.ts b/packages/tailwindcss/src/index.ts
index 6e493c3689d0..4907306eee84 100644
--- a/packages/tailwindcss/src/index.ts
+++ b/packages/tailwindcss/src/index.ts
@@ -624,14 +624,6 @@ async function parseCss(
     firstThemeRule.nodes = [context({ theme: true }, nodes)]
   }
 
-  // Replace the `@tailwind utilities` node with a context since it prints
-  // children directly.
-  if (utilitiesNode) {
-    let node = utilitiesNode as AstNode as Context
-    node.kind = 'context'
-    node.context = {}
-  }
-
   // Replace the `@variant` at-rules with the actual variant rules.
   if (variantNodes.length > 0) {
     for (let variantNode of variantNodes) {
@@ -659,6 +651,14 @@ async function parseCss(
   features |= substituteFunctions(ast, designSystem)
   features |= substituteAtApply(ast, designSystem)
 
+  // Replace the `@tailwind utilities` node with a context since it prints
+  // children directly.
+  if (utilitiesNode) {
+    let node = utilitiesNode as AstNode as Context
+    node.kind = 'context'
+    node.context = {}
+  }
+
   // Remove `@utility`, we couldn't replace it before yet because we had to
   // handle the nested `@apply` at-rules first.
   walk(ast, (node, { replaceWith }) => {

From b35f713366a98f7b11f9a999f870060d68cdde1a Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Fri, 16 May 2025 14:40:41 +0200
Subject: [PATCH 04/11] add `@apply` integration tests for Vue `<style>` blocks

---
 integrations/vite/vue.test.ts | 70 +++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/integrations/vite/vue.test.ts b/integrations/vite/vue.test.ts
index 7b5da2904e4c..d2766e1cd9de 100644
--- a/integrations/vite/vue.test.ts
+++ b/integrations/vite/vue.test.ts
@@ -71,3 +71,73 @@ test(
     await fs.expectFileToContain(files[0][0], ['.bar{'])
   },
 )
+
+test(
+  'error when using `@apply` without `@reference`',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "type": "module",
+          "dependencies": {
+            "vue": "^3.4.37",
+            "tailwindcss": "workspace:^"
+          },
+          "devDependencies": {
+            "@vitejs/plugin-vue": "^5.1.2",
+            "@tailwindcss/vite": "workspace:^",
+            "vite": "^6"
+          }
+        }
+      `,
+      'vite.config.ts': ts`
+        import { defineConfig } from 'vite'
+        import vue from '@vitejs/plugin-vue'
+        import tailwindcss from '@tailwindcss/vite'
+
+        export default defineConfig({
+          plugins: [vue(), tailwindcss()],
+        })
+      `,
+      'index.html': html`
+        <!doctype html>
+        <html>
+          <body>
+            <div id="app"></div>
+            <script type="module" src="./src/main.ts"></script>
+          </body>
+        </html>
+      `,
+      'src/main.ts': ts`
+        import { createApp } from 'vue'
+        import App from './App.vue'
+
+        createApp(App).mount('#app')
+      `,
+      'src/App.vue': html`
+        <template>
+          <div class="foo">Hello Vue!</div>
+        </template>
+
+        <style>
+          .foo {
+            @apply text-red-500;
+          }
+        </style>
+      `,
+    },
+  },
+  async ({ exec, expect }) => {
+    expect.assertions(1)
+
+    try {
+      await exec('pnpm vite build')
+    } catch (error) {
+      let [, message] = /error during build:([\s\S]*?)file:/g.exec(error.message) ?? []
+      expect(message.trim()).toMatchInlineSnapshot(`
+        "[@tailwindcss/vite:generate:build] Cannot apply unknown utility class: \`text-red-500\`.
+        It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`"
+      `)
+    }
+  },
+)

From 6fbb4318432599a71ebd7df8aa37cdf0483c278e Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 26 May 2025 15:36:59 +0200
Subject: [PATCH 05/11] normalize whitespace

---
 integrations/vite/vue.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/integrations/vite/vue.test.ts b/integrations/vite/vue.test.ts
index d2766e1cd9de..2c3d56f4dd6b 100644
--- a/integrations/vite/vue.test.ts
+++ b/integrations/vite/vue.test.ts
@@ -133,7 +133,8 @@ test(
     try {
       await exec('pnpm vite build')
     } catch (error) {
-      let [, message] = /error during build:([\s\S]*?)file:/g.exec(error.message) ?? []
+      let [, message] =
+        /error during build:([\s\S]*?)file:/g.exec(error.message.replace(/\r?\n/g, '\n')) ?? []
       expect(message.trim()).toMatchInlineSnapshot(`
         "[@tailwindcss/vite:generate:build] Cannot apply unknown utility class: \`text-red-500\`.
         It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`"

From 11adcbe0579c0046ad28cdd53cf7369f3c886431 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 26 May 2025 15:45:27 +0200
Subject: [PATCH 06/11] are there VT control characters? Who knows!

---
 integrations/vite/vue.test.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/integrations/vite/vue.test.ts b/integrations/vite/vue.test.ts
index 2c3d56f4dd6b..cec0181bfb47 100644
--- a/integrations/vite/vue.test.ts
+++ b/integrations/vite/vue.test.ts
@@ -1,3 +1,4 @@
+import { stripVTControlCharacters } from 'node:util'
 import { candidate, html, json, test, ts } from '../utils'
 
 test(
@@ -134,7 +135,9 @@ test(
       await exec('pnpm vite build')
     } catch (error) {
       let [, message] =
-        /error during build:([\s\S]*?)file:/g.exec(error.message.replace(/\r?\n/g, '\n')) ?? []
+        /error during build:([\s\S]*?)file:/g.exec(
+          stripVTControlCharacters(error.message.replace(/\r?\n/g, '\n')),
+        ) ?? []
       expect(message.trim()).toMatchInlineSnapshot(`
         "[@tailwindcss/vite:generate:build] Cannot apply unknown utility class: \`text-red-500\`.
         It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`"

From 75bdb44cbde06d91f3a10b2ae81b257d761e9d7f Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 26 May 2025 16:30:58 +0200
Subject: [PATCH 07/11] update changelog

---
 CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc14695211ce..c1ba5950d0c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Improve error messages when `@apply` fails ([#18059](https://github.com/tailwindlabs/tailwindcss/pull/18059))
+
 ### Fixed
 
 - Upgrade: Do not migrate declarations that look like candidates in `<style>` blocks ([#18057](https://github.com/tailwindlabs/tailwindcss/pull/18057), [18068](https://github.com/tailwindlabs/tailwindcss/pull/18068))

From 3f69a5f5a6baaee28d8754dbd47fe3d2332beacd Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 26 May 2025 16:42:23 +0200
Subject: [PATCH 08/11] rely on `Theme` to know when we are missing
 `@reference` or `@import "tailwindcss"`

This is a better single source of truth because `Theme` will be filled
in with the necessary data.
---
 packages/tailwindcss/src/apply.ts      | 24 ++++--------------------
 packages/tailwindcss/src/index.test.ts | 10 ++++++++--
 packages/tailwindcss/src/theme.ts      |  4 ++++
 3 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/packages/tailwindcss/src/apply.ts b/packages/tailwindcss/src/apply.ts
index b587ff5de82c..18d59b0b1e9b 100644
--- a/packages/tailwindcss/src/apply.ts
+++ b/packages/tailwindcss/src/apply.ts
@@ -197,26 +197,10 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
               )
             }
 
-            // Verify `@tailwind utilities` or `@reference` is used
-            let hasUtilitiesOrReference = false
-            walk(ast, (node, { context }) => {
-              // Find `@reference`
-              if (context.reference) {
-                hasUtilitiesOrReference = true
-                return WalkAction.Stop
-              }
-
-              // Find `@tailwind utilities`
-              else if (
-                node.kind === 'at-rule' &&
-                node.name === '@tailwind' &&
-                (node.params === 'utilities' || node.params.startsWith('utilities'))
-              ) {
-                hasUtilitiesOrReference = true
-                return WalkAction.Stop
-              }
-            })
-            if (!hasUtilitiesOrReference) {
+            // 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}\`.\nIt looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\``,
               )
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 0b9a5d5433e3..2e988337fa36 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -551,7 +551,10 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: Cannot apply unknown utility class: \`bg-not-found\`]`,
+      `
+      [Error: Cannot apply unknown utility class: \`bg-not-found\`.
+      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
+    `,
     )
   })
 
@@ -565,7 +568,10 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: Cannot apply unknown utility class: \`hocus:bg-red-500\`]`,
+      `
+      [Error: Cannot apply unknown utility class: \`hocus:bg-red-500\`.
+      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
+    `,
     )
   })
 
diff --git a/packages/tailwindcss/src/theme.ts b/packages/tailwindcss/src/theme.ts
index 2928afd3bd55..dc9c750a12f8 100644
--- a/packages/tailwindcss/src/theme.ts
+++ b/packages/tailwindcss/src/theme.ts
@@ -51,6 +51,10 @@ export class Theme {
     private keyframes = new Set<AtRule>([]),
   ) {}
 
+  get size() {
+    return this.values.size
+  }
+
   add(key: string, value: string, options = ThemeOptions.NONE, src?: Declaration['src']): void {
     if (key.endsWith('-*')) {
       if (value !== 'initial') {

From b578ca929cf03f377d006485f26437c3ace50dfc Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Mon, 26 May 2025 17:14:53 +0200
Subject: [PATCH 09/11] show unknown variants when using `@apply`

---
 packages/tailwindcss/src/apply.ts      | 23 +++++++++++++++++++++++
 packages/tailwindcss/src/index.test.ts | 12 +++++++++---
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/packages/tailwindcss/src/apply.ts b/packages/tailwindcss/src/apply.ts
index 18d59b0b1e9b..899d4467950c 100644
--- a/packages/tailwindcss/src/apply.ts
+++ b/packages/tailwindcss/src/apply.ts
@@ -4,6 +4,7 @@ import { compileCandidates } from './compile'
 import type { DesignSystem } from './design-system'
 import type { SourceLocation } from './source-maps/source'
 import { DefaultMap } from './utils/default-map'
+import { segment } from './utils/segment'
 
 export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
   let features = Features.None
@@ -197,6 +198,28 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
               )
             }
 
+            // Verify if variants exist
+            let parts = segment(candidate, ':')
+            if (parts.length > 1) {
+              let utility = parts.pop()!
+
+              // Ensure utility on its own compiles, if not, we will fallback to
+              // the next error
+              if (designSystem.candidatesToCss([utility])[0]) {
+                let compiledVariants = designSystem.candidatesToCss(
+                  parts.map((variant) => `${variant}:[--tw-variant-check:1]`),
+                )
+                let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)
+                if (unknownVariants.length > 0) {
+                  throw new Error(
+                    `Cannot apply unknown utility class: \`${candidate}\`.\nThe following variants are unknown:\n${unknownVariants
+                      .map((variant) => `- \`${variant}\``)
+                      .join('\n')}\n`,
+                  )
+                }
+              }
+            }
+
             // When the theme is empty, it means that no theme was loaded and
             // `@import "tailwindcss"`, `@reference "app.css"` or similar is
             // very likely missing.
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 2e988337fa36..63267356e2f2 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -562,15 +562,21 @@ describe('@apply', () => {
     await expect(
       compile(css`
         @tailwind utilities;
+        @theme {
+          --color-red-500: red;
+        }
 
         .foo {
-          @apply hocus:bg-red-500;
+          @apply hocus:hover:pocus:bg-red-500;
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
       `
-      [Error: Cannot apply unknown utility class: \`hocus:bg-red-500\`.
-      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
+      [Error: Cannot apply unknown utility class: \`hocus:hover:pocus:bg-red-500\`.
+      The following variants are unknown:
+      - \`hocus\`
+      - \`pocus\`
+      ]
     `,
     )
   })

From d1a60516096c2cbf8a7ef5e8e413815833d82399 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Tue, 27 May 2025 19:36:37 +0200
Subject: [PATCH 10/11] Apply suggestions from code review

Co-authored-by: Jonathan Reinink <jonathan@reinink.ca>
---
 packages/tailwindcss/src/apply.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/tailwindcss/src/apply.ts b/packages/tailwindcss/src/apply.ts
index 899d4467950c..d548792cb86f 100644
--- a/packages/tailwindcss/src/apply.ts
+++ b/packages/tailwindcss/src/apply.ts
@@ -180,7 +180,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
             // When using prefix, make sure prefix is used in candidate
             if (designSystem.theme.prefix && !candidate.startsWith(designSystem.theme.prefix)) {
               throw new Error(
-                `Cannot apply unprefixed utility class: \`${candidate}\`, did you mean \`${designSystem.theme.prefix}:${candidate}\`?`,
+                `Cannot apply unprefixed utility class \`${candidate}\`. Did you mean \`${designSystem.theme.prefix}:${candidate}\`?`,
               )
             }
 
@@ -230,7 +230,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
             }
 
             // Fallback to most generic error message
-            throw new Error(`Cannot apply unknown utility class: \`${candidate}\``)
+            throw new Error(`Cannot apply unknown utility class \`${candidate}\``)
           },
         })
 

From b47519f34628b8545054f29fb113dae0c711bcd3 Mon Sep 17 00:00:00 2001
From: Robin Malfait <malfait.robin@gmail.com>
Date: Tue, 27 May 2025 20:01:47 +0200
Subject: [PATCH 11/11] adjust error messages

---
 integrations/vite/vue.test.ts                 |  7 +++---
 packages/tailwindcss/src/apply.ts             | 22 +++++++++++++------
 .../tailwindcss/src/compat/config.test.ts     |  8 ++-----
 packages/tailwindcss/src/index.test.ts        | 18 +++------------
 packages/tailwindcss/src/prefix.test.ts       |  2 +-
 5 files changed, 24 insertions(+), 33 deletions(-)

diff --git a/integrations/vite/vue.test.ts b/integrations/vite/vue.test.ts
index cec0181bfb47..3a392bc03d71 100644
--- a/integrations/vite/vue.test.ts
+++ b/integrations/vite/vue.test.ts
@@ -138,10 +138,9 @@ test(
         /error during build:([\s\S]*?)file:/g.exec(
           stripVTControlCharacters(error.message.replace(/\r?\n/g, '\n')),
         ) ?? []
-      expect(message.trim()).toMatchInlineSnapshot(`
-        "[@tailwindcss/vite:generate:build] Cannot apply unknown utility class: \`text-red-500\`.
-        It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`"
-      `)
+      expect(message.trim()).toMatchInlineSnapshot(
+        `"[@tailwindcss/vite:generate:build] Cannot apply unknown utility class \`text-red-500\`. Are you using CSS modules or similar and missing \`@reference\`? https://tailwindcss.com/docs/functions-and-directives#reference-directive"`,
+      )
     }
   },
 )
diff --git a/packages/tailwindcss/src/apply.ts b/packages/tailwindcss/src/apply.ts
index d548792cb86f..691df2920a6e 100644
--- a/packages/tailwindcss/src/apply.ts
+++ b/packages/tailwindcss/src/apply.ts
@@ -194,7 +194,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
             // - `@source not inline(…)`
             if (designSystem.invalidCandidates.has(candidate)) {
               throw new Error(
-                `Cannot apply \`${candidate}\`, it seems like the utility was explicitly excluded and cannot be applied.\n\nMore info: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,
+                `Cannot apply utility class \`${candidate}\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes`,
               )
             }
 
@@ -211,11 +211,19 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
                 )
                 let unknownVariants = parts.filter((_, idx) => compiledVariants[idx] === null)
                 if (unknownVariants.length > 0) {
-                  throw new Error(
-                    `Cannot apply unknown utility class: \`${candidate}\`.\nThe following variants are unknown:\n${unknownVariants
-                      .map((variant) => `- \`${variant}\``)
-                      .join('\n')}\n`,
-                  )
+                  if (unknownVariants.length === 1) {
+                    throw new Error(
+                      `Cannot apply utility class \`${candidate}\` because the ${unknownVariants.map((variant) => `\`${variant}\``)} variant does not exist.`,
+                    )
+                  } 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.`,
+                    )
+                  }
                 }
               }
             }
@@ -225,7 +233,7 @@ export function substituteAtApply(ast: AstNode[], designSystem: DesignSystem) {
             // very likely missing.
             if (designSystem.theme.size === 0) {
               throw new Error(
-                `Cannot apply unknown utility class: \`${candidate}\`.\nIt looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\``,
+                `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`,
               )
             }
 
diff --git a/packages/tailwindcss/src/compat/config.test.ts b/packages/tailwindcss/src/compat/config.test.ts
index b28950dc28bd..196115d6357e 100644
--- a/packages/tailwindcss/src/compat/config.test.ts
+++ b/packages/tailwindcss/src/compat/config.test.ts
@@ -1239,7 +1239,7 @@ test('utilities used in @apply must be prefixed', async () => {
       },
     ),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `[Error: Cannot apply unprefixed utility class: \`underline\`, did you mean \`tw:underline\`?]`,
+    `[Error: Cannot apply unprefixed utility class \`underline\`. Did you mean \`tw:underline\`?]`,
   )
 })
 
@@ -1441,11 +1441,7 @@ test('blocklisted candidates cannot be used with `@apply`', async () => {
       },
     ),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `
-    [Error: Cannot apply \`bg-white\`, it seems like the utility was explicitly excluded and cannot be applied.
-
-    More info: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes]
-  `,
+    `[Error: Cannot apply utility class \`bg-white\` because it has been explicitly disabled: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes]`,
   )
 })
 
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 63267356e2f2..e34faca42925 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -294,10 +294,7 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `
-      [Error: Cannot apply unknown utility class: \`p-2\`.
-      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
-    `,
+      `[Error: Cannot apply unknown utility class \`p-2\`. Are you using CSS modules or similar and missing \`@reference\`? https://tailwindcss.com/docs/functions-and-directives#reference-directive]`,
     )
   })
 
@@ -551,10 +548,7 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `
-      [Error: Cannot apply unknown utility class: \`bg-not-found\`.
-      It looks like you are missing a \`@reference "app.css"\` or \`@import "tailwindcss";\`]
-    `,
+      `[Error: Cannot apply unknown utility class \`bg-not-found\`. Are you using CSS modules or similar and missing \`@reference\`? https://tailwindcss.com/docs/functions-and-directives#reference-directive]`,
     )
   })
 
@@ -571,13 +565,7 @@ describe('@apply', () => {
         }
       `),
     ).rejects.toThrowErrorMatchingInlineSnapshot(
-      `
-      [Error: Cannot apply unknown utility class: \`hocus:hover:pocus:bg-red-500\`.
-      The following variants are unknown:
-      - \`hocus\`
-      - \`pocus\`
-      ]
-    `,
+      `[Error: Cannot apply utility class \`hocus:hover:pocus:bg-red-500\` because the \`hocus\` and \`pocus\` variants do not exist.]`,
     )
   })
 
diff --git a/packages/tailwindcss/src/prefix.test.ts b/packages/tailwindcss/src/prefix.test.ts
index 32725f21074e..c60383de47e3 100644
--- a/packages/tailwindcss/src/prefix.test.ts
+++ b/packages/tailwindcss/src/prefix.test.ts
@@ -89,7 +89,7 @@ test('utilities used in @apply must be prefixed', async () => {
       }
     `),
   ).rejects.toThrowErrorMatchingInlineSnapshot(
-    `[Error: Cannot apply unprefixed utility class: \`underline\`, did you mean \`tw:underline\`?]`,
+    `[Error: Cannot apply unprefixed utility class \`underline\`. Did you mean \`tw:underline\`?]`,
   )
 })