Hydration mismatch errors in linked stylesheets.

[ambethia]

Which project does this relate to?

Start

Describe the bug

After making a change that introduces an exception in the css loading, once you've corrected the error, you'll get a persistent hydration mismatch until the vinxi server is restarted. This continues even after hard refreshes of the page.

Your Example Website or App

https://stackblitz.com/github/tanstack/router/tree/main/examples/react/start-basic

Steps to Reproduce the Bug or Issue

1. Make a change in the css with an error, e.g., sahflsdjfhls somewhere in the file.
2. See the error. HMR doesn't seem to work on stackblitz, but you'll see it locally immediately.
3. Correct the error. The CSS is fixed, but you'll have a hydration mismatch in the console.

Expected behavior

I expect to not have any error messages after correcting the CSS.

Screenshots or Videos

Video

Platform

• OS: macOS
• Browser: Chrome and Firefox

Additional context

I noticed while recording the video that the error happened again after restarting Vinxi without making any erroneous edits to the CSS, just refreshing the page. 🤷‍♂

[ambethia]

It does look like the stylesheet is being applied twice while this is happening.

[lsalling]

Can attest. Spent hours trying to debug thinking I configured Tailwind incorrectly.

[jasonsilberman]

Seeing this error with start 1.105.3 and tailwindcss 4.0.6 and @tailwindcss/vite 4.0.6.

[jackytea]

Also seeing this error with @tanstack/start 1.107.0 alongside tailwindcss 4.0.7 and @tailwindcss/vite 4.0.7.

[oveigam]

Also seeing this error with @tanstack/start 1.107.0 alongside tailwindcss 4.0.7 and @tailwindcss/vite 4.0.7.

To me the error appears every time you start the dev server and open the web for the first time: In production seems to happen every time i refresh the page

I think i found a workaround using postcss

• Remove the vite plugin from app.config.ts

• Install postcss and @tailwindcss/postcss

• Add the following postcss.config.mjs to your root folder

  // postcss.config.mjs
  export default {
    plugins: {
      "@tailwindcss/postcss": {},
    },
  };
  

[jackytea]

Also seeing this error with @tanstack/start 1.107.0 alongside tailwindcss 4.0.7 and @tailwindcss/vite 4.0.7.

To me the error appears every time you start the dev server and open the web for the first time: In production seems to happen every time i refresh the page

I think i found a workaround using postcss

* Remove the vite plugin from app.config.ts

* Install postcss and @tailwindcss/postcss

* Add the following postcss.config.mjs to your root folder
  // postcss.config.mjs
  export default {
    plugins: {
      "@tailwindcss/postcss": {},
    },
  };

@oveigam this works, thanks! Hopefully the root cause of this is resolved soon.

[jasonsilberman]

Fyi that tailwindcss + @tailwindcss/vite 4.0.8 fixed this for me!

[devnomic]

Still seeing this on 4.0.8 in my case.

Especially when i change app.css then refresh the page.

[sunxyw]

Upgrading to 4.0.8 fixes this for me.

[jccdev45]

Also getting this error with a new create-tsrouter-app. It happens with any change in the CSS, either in styles.css or any JSX. Restarting the dev server somewhat fixes it, editing styles.css reintroduces it but editing JSX is fine. Package versions:

• @tanstack/react-start 1.114.3
• tailwindcss 4.0.12 (upgraded from 4.0.6)
• @tailwindcss/vite 4.0.12 (upgraded from 4.0.6)
• @tailwindcss/postcss 4.0.12 (upgraded from 4.0.7)
• postcss 8.5.3 (upgraded from 8.5.2)

I do have a postcss.config.ts file with the same contents as what @oveigam suggested (generated by create-tsrouter-app)

[Zev18]

I still get this hydration issue, but restarting the server fixes it

[MGSimard]

Ran into these hydration issues myself as well while using tailwindcss; hydration error in localhost and 404 resource in prod (which delayed the CSS loading, causing unstyled flash). Looks to be some kind of path/filename resolving issue between server & client, as it references a randomized css module affix different than what the client has (BSr2kfh doesn't exist on client):

So with that I ended up finding this solution which fixed my issue: https://github.com/TanStack/router/issues/2899#issuecomment-2614144714

[nickgraffis]

I still run into this issue with the following set up

@import 'tailwindcss' source('../../../');
@import '@mmv3/ui/styles/global.css';

this to extend the source to include the ui section of the monorepo.

Anyone else run into this after trying #2899 ?

To clarify, it breaks here @import 'tailwindcss' source('../../../');.

[warmbowski]

removing @tailwindcss/vite seems to have worked for me. I already had a postcss.config.js file in the root of my project with the @tailwind/postcss plugin configured. I thought we needed both for tailwind to work, but I guess we don't. Maybe there was conflict between the two that cause the hydration mismatch?

[schiller-manuel]

can you please check if this issue still exists on the alpha version?

https://github.com/TanStack/router/discussions/2863#discussioncomment-13104960

[nachoaldamav]

Hi, the issue still happens in the alpha version 1.121.0-alpha.27 or at least for me, the only way to fix it in my side was to downgrade the TailwindCSS Vite plugin to 4.0.7.

From 4.0.8 some logic in the plugin changed in the way the classes are searched (see https://github.com/tailwindlabs/tailwindcss/discussions/16958#discussion-8042351).

ps: I tried all the solutions of switching to PostCSS, use source, etc...

[tomh4]

having this as well on the latest alpha

[SeanLatimer]

Hi, the issue still happens in the alpha version 1.121.0-alpha.27 or at least for me, the only way to fix it in my side was to downgrade the TailwindCSS Vite plugin to 4.0.7.

From 4.0.8 some logic in the plugin changed in the way the classes are searched (see tailwindlabs/tailwindcss#16958 (comment)).

ps: I tried all the solutions of switching to PostCSS, use source, etc...

Also seeing this on 1.121.27, downgrading to @tailwindcss/[email protected] fixed the hydration error which was being caused by a non existent css file being linked.

[junlarsen]

I saw a similar error on both 4.1.10 and 4.0.7, but my problem was that I tried to include styles as ?url and manually append them to the head. Letting vite take care of the CSS worked just fine.

 import { Paragraph } from "~/components/atoms/paragraph";
 import { Footer } from "~/components/molecules/footer";
 import { Header } from "~/components/molecules/header";
-import styles from "~/globals.css?url";
+import "../globals.css";

 export const Route = createRootRoute({
   head: () => ({
@@ -84,7 +84,6 @@ export const Route = createRootRoute({
         content: "nb-NO",
       },
     ],
-    links: [{ rel: "stylesheet", href: styles }],
   }),
   component: function RootLayout() {

[warmbowski]

@junlarsen that is interesting. I am doing that "?url" to and adding the link. Does this change add your global css inline in the head as a style tag, or does it still link it as a separate css file? Curious to hear what a Tanstack-start dev thinks about this, and if this is the best way to import global styles after moving off of vinxi.

[junlarsen]

Does this change add your global css inline in the head as a style tag, or does it still link it as a separate css file?

It produces a css file and inserts a link tag into the head.

For more context; having the ?url part resulted in the Vite build producing references to two different CSS files, but there was only one output by the build. The generated server files would reference the file that doesn't exist and try append it into the head which I'm guessing was the cause for the hydration error

[vVolodya]

@junlarsen fixed fouc and hydration error for me, thx

"tailwindcss": "^4.1.8" "vite": "^6.3.5" "@tanstack/react-start": "1.121.12"

[schiller-manuel]

going to close this now that the latest tailwindcss plugin seems to have resolved this issue. if anyone encounters any problem here, please open up a new issue including a complete example.

[nickgraffis]

@junlarsen I am experiencing the same thing as you. Your solution removes the server file trying to reference a non existent css file, but were you able to get it to properly reference the correct outputted css file?

Using latest tailwind plugin by the way

[junlarsen]

@junlarsen I am experiencing the same thing as you. Your solution removes the server file trying to reference a non existent css file, but were you able to get it to properly reference the correct outputted css file?

Using latest tailwind plugin by the way

Yeah everything works fine with what I showed in my original comment

[issamwahbi]

I did as @junlarsen proposed. The hydration problem is resolved but they is a flash when the app is loaded. First the page is displayed without CSS then formatted correctly.

[ericclemmons]

I did as @junlarsen proposed. The hydration problem is resolved but they is a flash when the app is loaded. First the page is displayed without CSS then formatted correctly.

I think this is because it's being injected via JS, not as part of the rendered HTML from the server.

However, the built version should include it? 🙏

[junlarsen]

I did as @junlarsen proposed. The hydration problem is resolved but they is a flash when the app is loaded. First the page is displayed without CSS then formatted correctly.

Yeah you're right. My largest project is still on vinxi so I hadn't actually noticed.

I think this is because it's being injected via JS, not as part of the rendered HTML from the server.

However, the built version should include it? 🙏

I believe it still happens with the built version sadly.

[AzrizHaziq]

Hi, i'm still facing this issue and for the time being we can add this -Hydration in dev-tool console. Yes it is short term solution.

 "vite": "^7.0.6",
 "tailwindcss": "^4.1.11",
 "@tanstack/react-start": "^1.130.15",
"@tailwindcss/postcss": "^4.1.11",
"@tailwindcss/vite": "^4.1.8",
"postcss": "^8.5.6",

[eldarshamukhamedov]

@issamwahbi @junlarsen did y'all ever figure out the FOUC issue that pops up after switching from ?url to import "../global.css"?