Tailwind CSS Debugging & Troubleshooting

Common Issues & Solutions

1. Styles Not Applying

Check Content Detection

v4 automatically detects content, but if styles are missing:

/* Explicitly specify sources */
@import "tailwindcss";
@source "./src/**/*.{html,js,jsx,ts,tsx,vue,svelte}";

Verify Class Names

<!-- WRONG - Dynamic class won't be detected -->
<div class={`text-${color}-500`}>

<!-- CORRECT - Use complete class names -->
<div class={color === 'blue' ? 'text-blue-500' : 'text-red-500'}>

Check Build Process

# Restart dev server
npm run dev

# Clear cache and rebuild
rm -rf node_modules/.vite
npm run build

2. v4 Migration Issues

PostCSS Plugin Changed

// OLD (v3)
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {}
  }
}

// NEW (v4)
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

Configuration Moved to CSS

/* v4 - Configure in CSS, not JS */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.6 0.2 250);
}

Dark Mode Variant

/* v4 - Add if using selector strategy */
@custom-variant dark (&:where(.dark, .dark *));

3. Classes Being Overridden

Check Specificity

/* Browser DevTools: Inspect element → Styles panel */
/* Look for crossed-out styles */

Solutions

<!-- Use !important (last resort) -->
<div class="!mt-0">

<!-- Or increase specificity with variants -->
<div class="[&]:mt-0">

Check Import Order

/* Your custom CSS should come after Tailwind */
@import "tailwindcss";
@import "./custom.css";  /* After Tailwind */

4. Typography Plugin Issues

Styles Not Applied

/* Ensure plugin is loaded */
@plugin "@tailwindcss/typography";

Utilities Overridden by Prose

<!-- Use element modifiers -->
<article class="prose prose-h1:text-4xl prose-a:text-blue-600">

<!-- Or escape prose entirely -->
<article class="prose">
  <div class="not-prose">
    <CustomComponent />
  </div>
</article>

5. Forms Plugin Issues

Styles Not Applied to Plain Inputs

<!-- Forms plugin only styles inputs with type attribute -->
<input type="text" />  <!-- ✓ Styled -->
<input />              <!-- ✗ Not styled -->

Using Class Strategy

@plugin "@tailwindcss/forms" {
  strategy: class;
}

<!-- Now explicitly opt-in -->
<input type="text" class="form-input" />

Debugging Tools

VS Code Extension

# Install Tailwind CSS IntelliSense
code --install-extension bradlc.vscode-tailwindcss

Features:

Autocomplete for class names
Hover previews showing CSS
Linting for errors
Color decorators

Debug Screens Plugin

npm install -D @tailwindcss/debug-screens

@plugin "@tailwindcss/debug-screens";

<!-- Shows current breakpoint in corner -->
<body class="debug-screens">

Browser DevTools

Inspect Element → See computed styles
Styles Panel → See which rules apply
Filter → Search for Tailwind classes
Computed Tab → See final computed values

Check Generated CSS

# Output CSS to file for inspection
npx tailwindcss -o output.css --content './src/**/*.{html,js}'

# With verbose logging
DEBUG=tailwindcss:* npm run build

v4 Specific Debugging

Check Plugin Loading

# Look for plugin-related errors
npm run build 2>&1 | grep -i plugin

Verify CSS Variable Output

/* In browser DevTools, check :root for variables */
:root {
  --color-blue-500: oklch(...);
  --spacing-4: 1rem;
}

Content Detection Issues

/* Add explicit sources if auto-detection fails */
@source "./src/**/*.tsx";
@source "./components/**/*.tsx";

/* Exclude paths */
@source not "./src/generated/**";

Common Error Messages

"Cannot find module '@tailwindcss/postcss'"

npm install -D @tailwindcss/postcss

"Unknown at-rule @theme"

Using v3 tooling with v4 syntax. Update your build setup:

npm install -D tailwindcss@latest @tailwindcss/postcss@latest

"Class 'X' doesn't exist"

Dynamic class generation issue:

// BAD
const classes = `bg-${dynamic}-500`

// GOOD
const colorMap = {
  primary: 'bg-blue-500',
  danger: 'bg-red-500'
}
const classes = colorMap[dynamic]

"Styles not updating in development"

# Restart dev server
npm run dev

# Clear Vite cache
rm -rf node_modules/.vite

# Clear Next.js cache
rm -rf .next

Performance Debugging

Large CSS Output

# Check CSS file size
ls -lh dist/assets/*.css

# If too large, check for:
# 1. Dynamic class generation
# 2. Unnecessary safelisting
# 3. Unused plugins

Slow Builds

# Time the build
time npm run build

# v4 should be very fast
# Full build: <1s
# Incremental: microseconds

Debugging Checklist

Initial Setup

Correct import: @import "tailwindcss";
PostCSS plugin: @tailwindcss/postcss (not tailwindcss)
Vite plugin: @tailwindcss/vite (if using Vite)
CSS file imported in entry point
Development server restarted after changes

Styles Not Applying

Class name is complete (no dynamic generation)
File is in content path
Browser cache cleared
No CSS specificity conflicts
Check DevTools for overridden styles

After Migration

tailwind.config.js removed or converted
@theme directive used for customization
PostCSS config updated
Dark mode variant added if using selector strategy
Plugins updated to v4-compatible versions

Production Issues

NODE_ENV=production
Build output includes styles
CSS file linked correctly
No dynamic class generation issues

Getting Help

Create Minimal Reproduction

# Create fresh project
npm create vite@latest repro -- --template react-ts
cd repro
npm install -D tailwindcss @tailwindcss/vite

# Add minimal code that shows the issue
# Share on GitHub Issues or Discord

tailwindcss-debugging

Tailwind CSS Debugging & Troubleshooting

Common Issues & Solutions

1. Styles Not Applying

Check Content Detection

Verify Class Names

Check Build Process

2. v4 Migration Issues

PostCSS Plugin Changed

Configuration Moved to CSS

Dark Mode Variant

3. Classes Being Overridden

Check Specificity

Solutions

Check Import Order

4. Typography Plugin Issues

Styles Not Applied

Utilities Overridden by Prose

5. Forms Plugin Issues

Styles Not Applied to Plain Inputs

Using Class Strategy

Debugging Tools

VS Code Extension

Debug Screens Plugin

Browser DevTools

Check Generated CSS

v4 Specific Debugging

Check Plugin Loading

Verify CSS Variable Output

Content Detection Issues

Common Error Messages

"Cannot find module '@tailwindcss/postcss'"

"Unknown at-rule @theme"

"Class 'X' doesn't exist"

"Styles not updating in development"

Performance Debugging

Large CSS Output

Slow Builds

Debugging Checklist

Initial Setup

Styles Not Applying

After Migration

Production Issues

Getting Help

Create Minimal Reproduction

Resources

Similar Skills