Upgrade to v4 doesn't work: Cannot apply unknown utility class: bg-opacity-50

[alexkiro]

What version of Tailwind CSS are you using?

v3.4.10 -> v4.1.7

What build tool (or framework if it abstracts the build tool) are you using?

• postcss 8.5.3
• vite 6.3.5

What version of Node.js are you using?

v22.11.0

What browser are you using?

N/A

What operating system are you using?

Linux

Describe your issue

Project cannot be migrated

$ npx @tailwindcss/upgrade --force

≈ tailwindcss v4.1.7

│ Searching for CSS files in the current directory and its subdirectories… 

│ ↳ Linked `./tailwind.config.js` to `./src/styles/main.css` 

│ Migrating JavaScript configuration files… 

│ ↳ The configuration file at `./tailwind.config.js` could not be automatically migrated to the new CSS configuration format, so your CSS has been updated to load your existing 
│   configuration file. 

│ Migrating stylesheets… 

│ ↳ Migrated stylesheet: `./src/styles/main.css` 

│ Updating dependencies… 

│ ↳ Updated package: `tailwindcss` 

│ Migrating templates… 

Error: Cannot apply unknown utility class: bg-opacity-50
    at onInvalidCandidate (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:18:410)
    at de (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:13:29803)
    at file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:18:373
    at D (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:3:1655)
    at Oe (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:18:172)
    at Qr (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:35:828)
    at async pn (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U7LQKMN6.mjs:35:1123)
    at async Ca (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/node/dist/index.mjs:10:3358)
    at async xs (file:///home/kiro/.npm/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/upgrade/dist/index.mjs:249:12967)

[philipp-spiess]

Hey! Make sure you include an @reference to your config CSS file when using @apply: https://tailwindcss.com/docs/upgrade-guide#using-apply-with-vue-svelte-or-css-modules

[alexkiro]

Hey! Make sure you include an @reference to your config CSS file when using @apply: https://tailwindcss.com/docs/upgrade-guide#using-apply-with-vue-svelte-or-css-modules

I'm not sure how to do that. I don't have a config CSS file, the upgrade tool couldn't migrate my js config file so it linked it in the main.css file:

│ ↳ The configuration file at `./tailwind.config.js` could not be automatically migrated to the new CSS configuration format, so your CSS has been updated to load your existing 
│   configuration file. 

And it indeed added this to the top of the ./src/styles/main.css file

@config '../../tailwind.config.js';

---

The weird things is that the offending class bg-opacity-50 is actually in the same main.css file, so I don't believe I can or need to add @reference in there since it's not in a component. It's not even the first usage of @apply in the file, the tool migrates half the file then stops in the middle at this particular one.

[philipp-spiess]

Oh so the @apply is inside the main.css file? Does it include an @import "tailwindcss"; to load the default theme? If you can send me the repro I can take a look!

[alexkiro]

Oh so the @apply is inside the main.css file? Does it include an @import "tailwindcss"; to load the default theme? If you can send me the repro I can take a look!

The @import "tailwindcss" import is not included before the migration; but the migration tool does automatically add it:

@import "tailwindcss";

And yes, there are many @apply in the main.css files, and it's this single one that appears to cause issues. If I remove the bg-opacity-50 from this class the migration actually finishes successfully:

.AC-message {
  @apply inline-flex items-center bg-opacity-50 text-white text-sm font-bold px-4 py-3;
}

---

The repo is private, so I can't share it unfortunately. I will try to see if I can create a separate reproducible example and put it here.

Many thanks, for taking your time for this issue!

[philipp-spiess]

Ohh I'm stupid, of course bg-opacity-50 doesn't work: We removed it! 🤦 https://tailwindcss.com/docs/upgrade-guide#removed-deprecated-utilities unfortunately the upgrade tool does not handle that specific case because in order to fix this it would need to set a bg color value too but it only looks at one class in isolation. You'll have to figure out what color is set here and then use bg-{color}/50

[alexkiro]

Ohh, haha, makes sense now. So I guess the solution is to manully fix any such usages before running the migration tool.

Thanks for the help!