MENU
  1. ホーム
  2. JS・フロントエンド
  3. 【Tailwind CSS v4】Cannot apply unknown utility class の直し方

【Tailwind CSS v4】Cannot apply unknown utility class の直し方

JS・フロントエンド
CSS のカードがひび割れて警告バッジが添えられた、Tailwind CSS v4 の @apply エラーを表したアイキャッチ画像
目次

この記事が解決する悩み

  • 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枚にまとめたもの
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 しているクラス名がそこに無いかを確認するのが近道ですよ。

【広告】XServerドメインならドメイン取得も運用もお得。

参考

本文の記述は以下の一次情報を確認して書いています。

あわせて読みたい

【広告】このサイトはConoHa WINGで運営しています。安定した高速サーバーで快適にブログを書けています。いつもありがとう！！

JS・フロントエンド
JavaScript migration Tailwind CSS
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

コメント

コメントする

CAPTCHA


目次