Error while Migrate from TailwindCSS V3 to V4 using npx @tailwindcss/upgrade

[codezeros]

i tried to upgrade from tailwindcss v3 to v4 using npx @tailwindcss/upgrade --force I got this error

PS C:\Users\name\Projects\portfolio> npx @tailwindcss/upgrade --force     
(node:50016) ExperimentalWarning: CommonJS module C:\Users\name\AppData\Roaming\npm\node_modules\npm\node_modules\debug\src\node.js is loading ES Module C:\Users\name\AppData\Roaming\npm\node_modules\npm\node_modules\supports-color\index.js using require().
Support for loading ES Module in require() is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
≈ tailwindcss v4.0.0

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

│ ↳ Linked `.\tailwind.config.ts` to `.\src\styles\globals.css` 

│ Migrating JavaScript configuration files…

│ ↳ Could not load the configuration file: `addUtilities({ ':root' : … })` defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg. 
│   `.scrollbar-none`.

I saw many were having the same issue, especially on Windows #15220 if any anyone know a solution pls tell me

[muhammad-fiaz]

Hello @codezeros

I had this same problem and i tried removing plugins from tailwindcss.config.ts or tailwindcss.config.js and it worked after removing them :) and you can add back based on the new tailwindcss v4 refer: https://tailwindcss.com/docs/functions-and-directives#plugin-directive and https://tailwindcss.com/docs/adding-custom-styles

[JPulkit17]

Hi @codezeros @muhammad-fiaz @wongjn can anyone please explain in detail what needs to be done as I am also facing this issue and not able to fix it.

[muhammad-fiaz]

hi @JPulkit17 could you share more detail about the issue you are facing?

[KostaJovic01]

hi @JPulkit17
im also hawing the same issue.

I had to remove a bunch of stuff from theme
and I had to remove everything from the extends

Note

I still don't see any kind of pattern which could cause this error eg.

• object keys wrapped in quotes
• using key: 'var(--some-variable)'
• inline comments

Tip

WHAT I DID

1. I backed up the entire tailwind.config.ts
2. removed everything from the original tailwind.config.ts
3. added one thing after the other and repeated the migration over and over again

I repeated step 3 until I was left with only the working tailwind.config.ts which got successfully migrated
im kinda lucky that my config ain't that big, its like 200 lines

Hope that helps

[codezeros]

Hello @KostaJovic01,

This issue is mainly caused by an existing or added plugin in the tailwind.config.ts. When removed, the migration works perfectly fine. Afterward, you can add the new plugin method by following the [plugin directive method](https://tailwindcss.com/docs/functions-and-directives#plugin-directive).

Also, note that many old npm packages can cause this issue because they do not yet support the new Tailwind CSS v4. You should use npx @tailwindcss/upgrade --force, but make sure to commit your code to Git as a backup beforehand.

If you still encounter issues with variables like var(--some-variable) after migrating successfully, it's usually due to undefined properties or having multiple CSS files that depend on tailwind.config.ts extensions. To resolve this, ensure that all your CSS is in a single file, such as globals.css, before migrating. This worked perfectly for me.

I hope this helps! :)

[arthurfaraujo]

i did the upgrade with the @tailwind/upgrade, removed the tailwind.config.js whatsoever but im still facing the addUtilities problem

≈ tailwindcss v4.1.5

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

│ Migrating stylesheets… 

│ ↳ `addUtilities({ ':root' : … })` defines an invalid utility selector. Utilities must be a single class name 
│   and start with a lowercase letter, eg. `.scrollbar-none`. in `.\src\styles\global.css` 

│ ↳ Migrated stylesheet: `.\src\styles\global.css`

│ Updating dependencies…

│ ↳ Updated package: `tailwindcss` 

│ ↳ Updated package: `@tailwindcss/vite` 

│ Migrating templates…

Error: `addUtilities({ ':root' : … })` defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg. `.scrollbar-none`.
    at addUtilities (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-NZOSKIBJ.mjs:22:3498)
    at plugin.theme.extend.colors (file:///C:/Users/arthu/dev/si-activities/node_modules/@heroui/theme/dist/chunk-K7DXBDMW.mjs:110:7)
    at Ir (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-NZOSKIBJ.mjs:28:2129)
    at Fr (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-NZOSKIBJ.mjs:28:1080)
    at async Lr (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-NZOSKIBJ.mjs:36:146)
    at async Zi (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-NZOSKIBJ.mjs:36:1079)
    at async ea (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/node/dist/index.mjs:12:3280)
    at async xl (file:///C:/Users/arthu/AppData/Local/npm-cache/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/upgrade/dist/index.mjs:241:12918)

im trying to use hero ui with astro but im facing this problem and nothing seems to solve it, i already tried what the hero ui docs says about the migration, but it didnt solve the problem either

[DrJKL]

I just hit this too. It had to do with merging multiple values with the same custom property.
e.g.

      backgroundColor: {
        foo: "white",
      },
      backgroundImage: {
        foo: "url(\"/app-assets.svg\")",
      },
      backgroundSize: {
        foo: "cover",
      },
      backgroundAttachment: {
        foo: "fixed",
      },
      backgroundRepeat: {
        foo: "no-repeat",
      },