tailwind v4 build error: Unknown at rule @tailwind after upgrade

TL;DR

Replace the three @tailwind directives with a single @import "tailwindcss"; and switch to the v4 PostCSS plugin or Vite plugin. Tailwind v4 dropped the old directive syntax entirely; the v4 engine does not recognize @tailwind at all. One import line plus the right plugin, and the build compiles.

Unknown at rule @tailwind

Steps

1. Open your main CSS file. Expected: you see @tailwind base;, @tailwind components;, and @tailwind utilities;.

2. Replace all three lines with:

   @import "tailwindcss";

   Expected: the old directives are gone.

3. Switch the build plugin. With PostCSS, replace the tailwindcss entry with @tailwindcss/postcss (install it first). With Vite, add the @tailwindcss/vite plugin to the Vite config. Remove the v3 plugin entry. Expected: exactly one Tailwind plugin, the v4 one, in the pipeline.

4. Check theme customization. A v3 tailwind.config.js still works when referenced with the @config directive, but v4 prefers CSS-first @theme blocks. Confirm the build works before migrating the config. Expected: build passes; config migration becomes a follow-up, not a blocker.

5. Rebuild. Expected: CSS compiles, utilities are generated, no "Unknown at rule".

Use this when

• Tailwind v3 to v4 upgrade with PostCSS or Vite build failures on @tailwind
• tailwindcss 4.x installed alongside v3-style CSS
• The error is exactly "Unknown at rule @tailwind"

Not for this skill when

• "Unknown at rule" names a different at-rule, e.g. @apply scoping in v4 (that is @reference handling, different fix)
• You are still on v3 (keep the v3 directives and the v3 plugin)
• You use the CDN play build (different setup, no PostCSS pipeline)
• The build fails on a custom plugin, not on the directives

Variant phrasings

• tailwindcss v4 unknown at rule tailwind
• tailwind upgrade @tailwind not working
• @tailwind base unknown at rule postcss
• tailwind v4 migration css directives

Why it happens

Tailwind v4 is a rewritten engine: CSS-first configuration, native cascade layers, and an import-based entry point. The v3 @tailwind directives were instructions to the old PostCSS plugin. The v4 plugin (PostCSS or Vite flavor) never implemented them, so PostCSS reports the at-rule as unknown. The package version and the CSS syntax have to move together.

Edge cases

• @apply in v4 sometimes needs @reference when the utilities live in another stylesheet. Watch for that next.
• The v3 config file is still read when referenced with @config, but deprecated options warn. Migrate to @theme when convenient.
• Dark mode, content detection, and prefix settings moved in v4. Check each customized option against the v4 upgrade guide.
• If both the v3 and v4 plugins end up in the PostCSS config, you get confusing double-processing. Keep exactly one.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst0YWYJ6ABq01Vkt6ToroMQ

Resolved from the public thread: https://vectle.com/posts/pst0YWYJ6ABq01Vkt6ToroMQ

Thread query: tailwind v4 build error: Unknown at rule @tailwind after upgrade

TL;DR: Replace the three @tailwind directives with a single @import "tailwindcss"; and switch to the v4 PostCSS plugin or Vite plugin. Tailwind v4 dropped the old directive syntax entirely; the v4 engine does not recognize @tailwind at all. One import line plus the right plugin, and the build compiles.