目次
「Cannot apply unknown utility class」が出たときの直し方
- Tailwind CSS v4 に上げた日から、
@apply を書いた CSS でビルドが止まる
- 「Cannot apply unknown utility class」としか出ず、どの書き方が悪いのか分からない
- v3 では通っていた書き方が、どれが v4 で無効になったのか知りたい
対象読者: Tailwind CSS を v4 に上げた(またはこれから上げる)フロントエンドの開発者
前提知識: CSS の
@layer と Tailwind の
@apply の使い方。
結論
原因は1つです。v4 の
@apply は「Tailwind がユーティリティとして登録したクラス」しか展開できません。
| 書いていたもの |
v4 での直し方 |
@layer components や @layer utilities に置いた独自クラス |
@utility に変える |
tailwind.config.js に足したカスタム色 |
@theme で定義する(または @config で読ませる) |
Vue / Svelte の style ブロック、CSS Modules の中の @apply |
ファイル先頭に @reference を足す |
v3 の @tailwind base; などが残った CSS |
@import "tailwindcss"; に置き換える |
実務でいちばん多いのは1つ目です。
@layer components を
@utility に置き換えるだけで通ります。
@import "tailwindcss";
@utility btn {
@apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}
/* 実行結果
≈ tailwindcss v4.3.3
Done in 28ms */
ここからは原因ごとに、ビルドでエラーになる CSS と実行結果を並べていきますね。
エラーの正体
v4 の
@apply の役割は「既存のユーティリティクラスを自分の CSS にインライン展開する」ことです。
展開先の一覧に載っていないクラス名は、定義がどこにあっても引けません。これが
unknown utility class の意味です。
背景は公式のアップグレードガイドに書かれています。v3 は
@layer utilities や
@layer components に書いた独自クラスを「本物のユーティリティ」として取り込み、
hover: などのバリアントを効かせていました。
v4 はネイティブのカスケードレイヤーを使うようになり、
@layer を乗っ取るのをやめました。代わりに導入されたのが
@utility です。
検証には Tailwind CSS 4.3.3 の CLI を単体で使いました。
@import "tailwindcss"; を書いた CSS を1枚入力にして、ビルドが通るかどうかだけを見ます。
# 実行結果
$ node --version
v26.8.2
$ npm --version
11.19.1
$ node node_modules/@tailwindcss/cli/dist/index.mjs -i src/case1.css -o dist/case1.css
≈ tailwindcss v4.3.3
Error:
┌
│ Error: Cannot apply unknown utility class `btn`
└
エラーはスタックトレースも行番号も出しません。「そのクラス名が登録済みか」だけを見ているからですね。
ケース1: @layer components に書いた独自クラスを @apply している
v3 でよく使われていたパターンです。v4 ではここに書いたクラスがユーティリティ一覧に入らないので、
@apply のところで止まりますよ。
@layer utilities に書いた場合も同じエラーになります。
/* src/case1.css */
@import "tailwindcss";
@layer components {
.btn {
@apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}
}
.cta {
@apply btn;
}
/* 実行結果
≈ tailwindcss v4.3.3
Error: Cannot apply unknown utility class `btn` */
直し方は定義だけを
@utility に移すことです。
.cta から
@apply btn する書き方はそのまま使えます。
/* src/case1-fix.css */
@import "tailwindcss";
@utility btn {
@apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}
.cta {
@apply btn;
}
/* 実行結果(dist/case1-fix.css から抜粋)
.cta {
border-radius: var(--radius-lg);
background-color: var(--color-blue-500);
padding-inline: calc(var(--spacing) * 4);
padding-block: calc(var(--spacing) * 2);
color: var(--color-white);
} */
ケース2: tailwind.config.js のカスタム色を @apply している
v4 は JS の設定ファイルを自動では読みません。公式ガイドにも no longer detected automatically と書かれています。
設定はリポジトリに残っているのに
@apply だけが失敗するので、原因が分かりにくいケースですね。
// tailwind.config.js
export default {
theme: {
extend: {
colors: {
brand: "#7c3aed",
},
},
},
};
/* src/case2.css */
@import "tailwindcss";
.hero {
@apply bg-brand px-4 py-2 text-white;
}
/* 実行結果
≈ tailwindcss v4.3.3
Error: Cannot apply unknown utility class `bg-brand` */
直し方は2つあります。設定ファイルを
@config で明示的に読ませるか、値を CSS 側の
@theme に移すかです。
新規に書くなら
@theme が本筋で、既存の設定をそのまま使いたいときは
@config が1行で済みます。
/* src/case2-fix.css */
@config "../tailwind.config.js";
@import "tailwindcss";
.hero {
@apply bg-brand px-4 py-2 text-white;
}
/* 実行結果(dist/case2-fix.css から抜粋)
.hero {
background-color: #7c3aed;
padding-inline: calc(var(--spacing) * 4);
padding-block: calc(var(--spacing) * 2);
color: var(--color-white);
} */
ケース3: 別ファイルで @apply している(Vue・CSS Modules)
Vue や Svelte の
style ブロック、CSS Modules のファイルはメインの CSS とは別にコンパイルされます。
そのファイルからはテーマ変数もユーティリティ一覧も見えないので、組み込みの
rounded-lg ですら未登録扱いになります。
同じ状況を再現するために、そのファイルだけを入力にして CLI をかけます。
/* src/case3.css — メインの CSS を読まずに単体でコンパイル */
.card {
@apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}
/* 実行結果
≈ tailwindcss v4.3.3
Error: Cannot apply unknown utility class `rounded-lg`. Are you using CSS modules
or similar and missing `@reference`?
https://tailwindcss.com/docs/functions-and-directives#reference-directive */
このケースだけはエラー本文が解決策を教えてくれますよ。先頭に
@reference でメインの CSS を指すと通ります。
指したファイルの中身は出力に複製されません。変数の解決に使われるだけです。
/* src/case3-fix.css */
@reference "./styles.css";
.card {
@apply rounded-lg bg-blue-500 px-4 py-2 text-white;
}
/* 実行結果(dist/case3-fix.css から抜粋)
.card {
border-radius: var(--radius-lg, 0.5rem);
background-color: var(--color-blue-500, oklch(62.3% 0.214 259.815));
padding-inline: calc(var(--spacing, 0.25rem) * 4);
} */
ケース4: v3 の @tailwind ディレクティブが残っている
@tailwind base; などの3行は、v4 ではエラーになりません。気づかないうちに無視されます。
ただしテーマが読み込まれないので、次の
@apply が未登録クラスとして落ちます。メッセージはケース3と同じ形です。
/* src/case4.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
.hero {
@apply px-4 py-2;
}
/* 実行結果
≈ tailwindcss v4.3.3
Error: Cannot apply unknown utility class `px-4`. Are you using CSS modules
or similar and missing `@reference`?
https://tailwindcss.com/docs/functions-and-directives#reference-directive */
ここで
@reference を足すのは間違いです。このファイルはメインの CSS そのものなので、
@import "tailwindcss"; に置き換えるのが正解です。
/* src/case4-fix.css */
@import "tailwindcss";
.hero {
@apply px-4 py-2;
}
/* 実行結果
≈ tailwindcss v4.3.3
Done in 26ms */
つまずきポイント
@reference のパスは、そのファイルからの相対で解決される。../styles.css のように1つ上を指すと Can't resolve '../styles.css' in '...src' で止まる。エラー本文に出たディレクトリがヒントになる
tailwind.config.js が ESM なのに package.json に type: module が無いと、MODULE_TYPELESS_PACKAGE_JSON の警告が出る。動作はするが Reparsing の警告がログを埋める
@config の位置は @import "tailwindcss"; の前でも後でも動いた(4.3.3 で確認)
検証環境
| OS |
Windows 11 (build 10.0.26200) |
| CPU |
AMD Ryzen 9 PRO 8945HS w/ Radeon 780M Graphics |
| メモリ |
28GB |
| 言語/ツール |
Tailwind CSS 4.3.3 と @tailwindcss/cli 4.3.3(npm で一時ディレクトリ内に install) / Node.js 26.8.2(公式ポータブル配布 node-v26.8.2-win-x64.zip を展開) |
| 使用コマンド |
tailwindcss CLI(-i / -o)で case1〜case4 のエラーになる CSS と修正版をビルド / npm install / node –version / grep で生成された CSS を確認 |
| 測定日 |
2026-09-23 |
上記の環境で実際に実行して確認した結果です。環境が異なる場合は挙動が変わることがあります。
Tailwind CSS 4.3.3 の CLI に @apply 入りの CSS をビルドさせた実測ログ。@layer components の独自クラス・tailwind.config.js のカスタム色・メイン CSS を読まない別ファイル・v3 の @tailwind ディレクティブという4パターンで Cannot apply unknown utility class が再現すること、@utility / @config / @reference / @import "tailwindcss" の4つの直し方でビルドが通り生成 CSS が展開されることまでを1枚にまとめたもの
まとめ
@apply が通らないときは、まず「そのクラス名が Tailwind に登録されているか」を疑います。
v3 の書き方をそのまま持ってきた箇所が犯人なので、置き換え先さえ分かれば作業は数分で終わります。
| 原因 |
v3 の書き方 |
v4 の書き方 |
| 独自クラス |
@layer components { .btn { ... } } |
@utility btn { ... } |
| カスタム色 |
tailwind.config.js が自動で読まれる |
@theme か @config |
別ファイルの @apply |
そのまま書けた |
先頭に @reference |
| CSS の入口 |
@tailwind base; などの3行 |
@import "tailwindcss"; の1行 |
まずは
@layer components と
@layer utilities を検索して、
@apply しているクラス名がそこに無いかを確認するのが近道ですよ。
参考
本文の記述は以下の一次情報を確認して書いています。
あわせて読みたい
【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう!!
コメント