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

[codezeros]

This. If that addUtilities({ ':root' : … }) call is your own code, you can add the v4-equivalent back in after migrating.

yeah tailwindcss v4 has major changes so after migrating I added the plugins again based on the new tailwind v4

Thanks It works now!

PS C:\Users\name\Projects\portfolio> npx @tailwindcss/upgrade --force
(node:31448) 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…

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

│ Migrating templates…

│ ↳ Migrated templates for configuration file: `.\tailwind.config.ts` 

│ Migrating stylesheets…

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

│ Migrating PostCSS configuration…

│ ↳ The PostCSS config contains dynamic JavaScript and can not be automatically migrated.

│ Updating dependencies…

│ ↳ Updated package: `prettier-plugin-tailwindcss` 

│ ↳ Updated package: `tailwindcss` 

│ Verify the changes and commit them to your repository. 
PS C:\Users\name\Projects\portfolio> 

[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! :)

[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",
      },