Debugging & Common Pitfalls

A practical checklist for the usual Tailwind problems, from missing classes to specificity and dark-mode surprises.

4 min read Level 2/5 #tailwind#debugging#pitfalls

What you'll learn

Diagnose missing classes from dynamic strings or @source
Resolve specificity and order surprises
Fix arbitrary-value and dark-mode mistakes

Most Tailwind bugs have a short list of causes. Work through them in order before suspecting anything exotic.

My Class Does Nothing

The class probably was never generated. Common reasons:

The name was built from fragments — write complete strings.
The file is not scanned — add @source "./that/path";.
A plugin that defines the utility is not registered with @plugin.

Inspect the element in DevTools: if the class is not in the stylesheet at all, it is a detection problem, not a CSS problem.

// Generated nothing:
<div className={`mt-${gap}`} />
// Fix: full class names
<div className={gap === 4 ? 'mt-4' : 'mt-8'} />

Two Utilities Fight

When p-2 and p-4 both apply, the winner is whichever comes later in the generated CSS — not your string order. Use tailwind-merge so prop overrides resolve predictably.

Pseudo-Element Has No Content

before: and after: elements need an explicit content value or they do not render:

<span class="before:content-[''] before:block before:h-px before:bg-gray-300"></span>

Dark Mode Does Nothing

Class-strategy dark mode is opt-in in v4. Without the custom variant, dark: only follows the OS setting:

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

Arbitrary Values Fail

Arbitrary values cannot contain spaces — use underscores, and escape literal underscores. bg-[url(/a_b.png)] becomes bg-[url(/a\_b.png)].

Migrating v3 → v4 →