Tailwind v4 persistent cache stuck on CSS syntax errors in Next.js (Turbopack & Monorepo)
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 142k
- Forks
- 32.4k
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 351
Description
Link to the code that reproduces this issue
https://github.com/NapsterDinh/reproduce-turbopack-issue
To Reproduce
Case 1: Standard Root Structure (with Turbopack)
Reproduce: https://codesandbox.io/p/live/222f9507-4106-469c-8172-d5b12d51b379
- Use Next.js 15 with Tailwind v4 and enable Turbopack (next dev --turbo).
- In a CSS Module (e.g., Button.module.css), use @reference "../../app/globals.css";.
- Introduce a syntax error in globals.css (e.g., remove a closing brace }).
- Next.js shows the compilation error.
- Fix the error in globals.css.
- Result: The error overlay stays in the browser. Refreshing or restarting the server does not help.
- This error is only disappear when i clear my .next folder or switch to run dev with --webpack flag
Case 2: Monorepo Structure (Turbopack & Webpack) - [More Severe]
Reproduct: https://github.com/NapsterDinh/reproduce-turbopack-issue
- Setup a Monorepo where apps/web imports a CSS file from packages/ui/globals.css.
- In apps/web/app/globals.css, use @import "@repo/ui/globals.css";.
- Introduce a syntax error in the source file: packages/ui/globals.css.
- Result: The app crashes with a syntax error.
- Fix the error in packages/ui/globals.css.
- Observation: Even after restarting the dev server with either --turbo or --webpack, the error persists. The build process seems to be serving a cached version of the broken CSS file indefinitely.
Current vs. Expected behavior
Expected behavior
Next.js and the Tailwind v4 engine should invalidate the cache and re-parse the CSS files as soon as the file watcher detects a fix, clearing the error overlay without requiring a manual .next deletion.
Actual behavior
The error state is cached persistently. It appears the dependency graph (especially when involving @reference or cross-package imports) fails to trigger a clean rebuild after a hard syntax error occurs.
Provide environment information
Next.js Version: 16.1.5
Tailwind CSS Version: 4.2.1
Node.js Version: 24.10.0
Package Manager: pnpm
Operating System: macOS / Windows
Which area(s) are affected? (Select all that apply)
Turbopack, Webpack
Which stage(s) are affected? (Select all that apply)
next dev (local)
Additional context
The issue is significantly worse in Monorepos because the file is outside the app's root, potentially confusing the invalidation logic.
This bug completely breaks the development workflow, as any typo requires a full rm -rf .next and a cold start, which is time-consuming in large projects.
Temporary workaround: rm -rf .next && next dev.
Supplement: Comparison with Vite (HMR behavior)
I suspect this is a cache invalidation failure within Next.js's build engine. Vite demonstrates that the Tailwind v4 compiler can recover from these errors seamlessly. However, Next.js appears to fail in re-scanning or re-linking the @reference dependency once a hard syntax error has been cached, suggesting that the link between the CSS Module and the referenced file is being lost or stuck in an error state in the .next directory.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked reproducer and the CSS entry points named in the report: apps/web/app/globals.css, packages/ui/globals.css, and Button.module.css. Compare --turbo and --webpack after fixing the syntax error, then verify that the error overlay clears without deleting .next or restarting from a cold cache.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, nextjs, tailwindcss, webpack
- Domain
- build-system, devtools
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100