tailwindlabs/tailwindcss · error · Error

The prefix "${resolvedConfig.prefix}" is invalid. Prefixes m

Error message

The prefix "${resolvedConfig.prefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only.

What it means

Thrown when validating a prefix from JS config against `IS_VALID_PREFIX = /^[a-z]+$/`. After automatically trimming a trailing `-` (with a warning), if the remaining prefix contains anything other than lowercase a-z (digits, uppercase, symbols), it is rejected. The prefix is only set once, when `designSystem.theme.prefix` is not already populated from CSS.

Source

Thrown at packages/tailwindcss/src/compat/apply-compat-hooks.ts:376

  applyConfigToTheme(designSystem, resolvedUserConfig, replacedThemeKeys)
  applyKeyframesToTheme(designSystem, resolvedUserConfig)

  registerThemeVariantOverrides(resolvedUserConfig, designSystem)
  registerScreensConfig(resolvedUserConfig, designSystem)
  registerContainerCompat(resolvedUserConfig, designSystem)

  // If a prefix has already been set in CSS don't override it
  if (!designSystem.theme.prefix && resolvedConfig.prefix) {
    if (resolvedConfig.prefix.endsWith('-')) {
      resolvedConfig.prefix = resolvedConfig.prefix.slice(0, -1)

      console.warn(
        `The prefix "${resolvedConfig.prefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only and is written as a variant before all utilities. We have fixed up the prefix for you. Remove the trailing \`-\` to silence this warning.`,
      )
    }

    if (!IS_VALID_PREFIX.test(resolvedConfig.prefix)) {
      throw new Error(
        `The prefix "${resolvedConfig.prefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only.`,
      )
    }

    designSystem.theme.prefix = resolvedConfig.prefix
  }

  // If an important strategy has already been set in CSS don't override it
  if (!designSystem.important && resolvedConfig.important === true) {
    designSystem.important = true
  }

  if (typeof resolvedConfig.important === 'string') {
    let wrappingSelector = resolvedConfig.important

    walk(ast, (node, _ctx) => {
      if (node.kind !== 'at-rule') return
      if (node.name !== '@tailwind' || node.params !== 'utilities') return

View on GitHub (pinned to 16e94cbf7f)

Solutions

Change the prefix to lowercase ASCII letters only, e.g. `prefix: 'tw'`.
If you need a numeric or mixed-case namespace, use CSS layering or build-time class renaming outside Tailwind's prefix feature.
Re-run after removing any trailing `-` to silence the related warning.

Example fix

// before (tailwind.config.js)
module.exports = { prefix: 'Tw2-' }
// after
module.exports = { prefix: 'tw' }

Defensive patterns

Strategy: validation

Validate before calling

const IS_VALID_PREFIX = /^[a-z]+$/;
function assertValidPrefix(prefix) {
  let p = prefix.endsWith('-') ? prefix.slice(0, -1) : prefix;
  if (!IS_VALID_PREFIX.test(p)) throw new Error(`Invalid prefix: ${prefix}`);
}
// assertValidPrefix(config.prefix);

Prevention

Restrict prefixes to `^[a-z]+$` at authoring time.
Add a config-schema check (zod/json-schema) validating `prefix` before build.

When it happens

Trigger: Setting `prefix: 'Tw'`, `prefix: 'tw2'`, `prefix: 't_w'`, or `prefix: 't.w'` in `tailwind.config.js`. Each fails the regex after the trailing-dash fixup.

Common situations: Using a brand-style prefix with mixed case or numbers; migrating a v3 prefix that contained disallowed characters; misreading the docs as allowing any string.

Related errors

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