tailwindlabs/tailwindcss · error · Error

It looks like you're trying to use `tailwindcss` directly as

Error message

It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install `@tailwindcss/postcss` and update your PostCSS configuration.

What it means

Thrown by the default export of the `tailwindcss` package when it is invoked as a PostCSS plugin. In v4 the PostCSS integration moved to a dedicated `@tailwindcss/postcss` package; importing `tailwindcss` and adding it to `postcss([tailwindcss])` is no longer supported and this guard throws immediately to surface the migration requirement.

Source

Thrown at packages/tailwindcss/src/index.ts:868

      return compiledCss
    },

    buildSourceMap() {
      return createSourceMap({
        ast: compiledAst,
      })
    },
  }
}

export async function __unstable__loadDesignSystem(css: string, opts: CompileOptions = {}) {
  let result = await parseCss(CSS.parse(css, { from: opts.from }), opts)
  return result.designSystem
}

export default function postcssPluginWarning() {
  throw new Error(
    `It looks like you're trying to use \`tailwindcss\` directly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install \`@tailwindcss/postcss\` and update your PostCSS configuration.`,
  )
}

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Install the dedicated plugin: `npm install @tailwindcss/postcss`.
2. Update `postcss.config.js` to use `@tailwindcss/postcss` instead of `tailwindcss`.
3. If using the Vite/webpack/etc. integrations, switch to the matching first-party package (`@tailwindcss/vite`, `@tailwindcss/postcss`, etc.) and remove the PostCSS entry.

Example fix

// before — postcss.config.js (v3)
module.exports = { plugins: { tailwindcss: {} } }

// after — postcss.config.js (v4)
module.exports = { plugins: { '@tailwindcss/postcss': {} } }

// Fail fast in CI if postcss config references the wrong package.
import { existsSync, readFileSync } from 'node:fs'

function validatePostcssConfig(path = 'postcss.config.js'): string | null {
  if (!existsSync(path)) return null
  const src = readFileSync(path, 'utf8')
  if (/\btailwindcss\s*:/.test(src) && !/@tailwindcss\/postcss/.test(src)) {
    return 'postcss.config.js references tailwindcss directly; install @tailwindcss/postcss and update the config'
  }
  return null
}

When it happens

Trigger: A `postcss.config.js` containing `module.exports = { plugins: { tailwindcss: {} } }` after upgrading to v4, or programmatic `postcss([require('tailwindcss')]).process(...)`.

Common situations: Upgrading from Tailwind v3 to v4 without updating the PostCSS config; scaffolding from an outdated template or tutorial; a shared config file used across projects at different versions.

Related errors

• No `loadStylesheet` function provided to `compile`
• Invalid theme value `${value}` for namespace `${key}`
• Cannot use `@variant` with unknown variant: ${variant}

AI-assisted analysis of tailwindlabs/tailwindcss@16e94cbf7f (2026-08-12). Data as JSON: /api/errors/e0bfd72cf86192c0. Report an issue: GitHub.