Diagnosing Missing Tailwind CSS Utility Classes Due to Content Configuration

Recognizable condition

After building or watching the project, certain Tailwind utility classes such as flex, text-red-500, or hover:bg-blue-600 are missing from the generated CSS file, causing elements to appear unstyled or using fallback styles.

Cause / diagnostic table

Symptom	Likely cause
Specific utilities absent from build/css/tailwind.css	Content paths in tailwind.config.js do not match the locations of your template files
All utilities missing	Content array empty or pointing to wrong root
Only utilities from certain directories missing	Glob pattern excludes those directories or uses overly restrictive exclude

Ordered checks

1. Open tailwind.config.js and verify the content array includes every directory or glob that contains HTML, JSX, Vue, Svelte, or other templated files.
2. Ensure each path is relative to the project root and uses correct glob syntax (e.g., ./src/**/*.{html,js,jsx,ts,tsx,vue}).
3. Run Tailwind in watch mode with debug output to see which files are being scanned:

   TAILWIND_MODE=watch npx tailwindcss -i ./src/input.css -o ./dist/tailwind.css --watch

   Look for lines like Scanning ... in the terminal.
4. Inspect the generated CSS file (e.g., dist/tailwind.css) for the missing utility. Use grep to confirm:

   grep '\\bflex\\b' dist/tailwind.css

   If the line returns nothing, the class was purged.
5. As a quick test, temporarily replace the content array with [ '*/*' ] and rebuild. If the missing utilities appear, the issue is definitely a content‑path mismatch.

Fixes tied to findings

Add missing paths or correct globs

Edit tailwind.config.js to include the missing directories. Example:

module.exports = {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx,vue}',
    './public/**/*.html',
    './components/**/*.{js,jsx,ts,tsx,vue}'
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};

Save the file and restart the development server or rebuild the production bundle.

Remove overly restrictive exclusions

If you have an exclude property, verify it does not unintentionally filter out needed files:

module.exports = {
  content: {
    raw: [
      './src/**/*.{html,js,jsx,ts,tsx,vue}'
    ],
    exclude: [] // ensure no needed paths are listed here
  },
  // …
};

Restart the scanner

Changes to tailwind.config.js are only picked up after the Tailwind JIT process restarts. Stop any running npm run dev or yarn dev process and start it again, or run a fresh build:

npm run build

Escalation criteria

If the missing utilities still do not appear after verifying and correcting the content array:

• Check for custom extractors or safelist configurations that might be overriding class usage. Look for safelist in tailwind.config.js and ensure it does not inadvertently whitelist only a subset.
• Confirm that the version of Tailwind CSS you are using is compatible with the PostCSS plugin version. A mismatch can cause the JIT scanner to ignore the content setting.
• Exclude any third‑party CSS processing steps (e.g., PurgeCSS separate from Tailwind) that could be stripping utilities after Tailwind generates them.
• If you are using a monorepo or workspace, verify that the content paths are resolved correctly from the workspace root; you may need to use path.resolve or relative paths from the config file’s location.

After applying any of the above steps, repeat the verification checks (grep the generated CSS and reload the browser) to confirm the utility is present and the styling appears as expected.