tailwindlabs/tailwindcss · error · Error

The --alpha(…) function requires a color and an alpha value,

Error message

The --alpha(…) function requires a color and an alpha value, e.g.: `--alpha(${color || 'var(--my-color)'} / ${alpha || '50%'})`

What it means

Thrown by the `--alpha(...)` CSS function handler when the input cannot be split on `/` into both a color and an alpha component. The handler does `segment(value, '/')` and trims both halves; if either half is empty the function cannot compute `withAlpha(color, alpha)` and rejects the call. `--alpha` is a v4 replacement for the old `theme(... alpha(...))` pattern and expects exactly `--alpha(<color> / <alpha>)`.

Source

Thrown at packages/tailwindcss/src/css-functions.ts:29

  string,
  (designSystem: DesignSystem, source: AstNode, ...args: string[]) => string
> = {
  '--alpha': alpha,
  '--spacing': spacing,
  '--theme': theme,
  theme: legacyTheme,
}

function alpha(
  _designSystem: DesignSystem,
  _source: AstNode,
  value: string,
  ...rest: string[]
): string {
  let [color, alpha] = segment(value, '/').map((v) => v.trim())

  if (!color || !alpha) {
    throw new Error(
      `The --alpha(…) function requires a color and an alpha value, e.g.: \`--alpha(${color || 'var(--my-color)'} / ${alpha || '50%'})\``,
    )
  }

  if (rest.length > 0) {
    throw new Error(
      `The --alpha(…) function only accepts one argument, e.g.: \`--alpha(${color || 'var(--my-color)'} / ${alpha || '50%'})\``,
    )
  }

  return withAlpha(color, alpha)
}

function spacing(
  designSystem: DesignSystem,
  _source: AstNode,
  value: string,
  ...rest: string[]

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Provide both parts separated by ` / `, e.g. `--alpha(var(--my-color) / 50%)` or `--alpha(red / 0.5)`.
2. If the color or alpha comes from a variable, ensure the variable is non-empty at build time.
3. Use a percentage (0%–100%) or a number (0–1) for the alpha segment.
4. Switch to the `color-mix()` CSS function if you need finer control.

Example fix

/* before */
.btn { color: --alpha(var(--brand)); }
/* after */
.btn { color: --alpha(var(--brand) / 50%); }

function isValidAlphaCall(input: string): boolean {
  const [color, alpha] = input.split('/').map(s => s?.trim() ?? '');
  return Boolean(color && alpha);
}
// Before emitting CSS:
if (!isValidAlphaCall(rawInner)) {
  throw new Error(`Refusing to emit --alpha(${rawInner}) — missing color or alpha`);
}

function isCompleteAlphaPair(inner: string): boolean {
  const parts = inner.split('/');
  return parts.length === 2 && parts[0].trim() !== '' && parts[1].trim() !== '';
}

When it happens

Trigger: Writing `--alpha(var(--my-color))` (no slash or alpha), `--alpha(/ 50%)` (missing color), `--alpha(red /)` (slash present but empty alpha after trim), or `--alpha()` (empty). The split yields only one segment or an empty second segment.

Common situations: Forgetting the slash separator when migrating from `rgba()`; passing a CSS variable that resolves to empty; copy-paste that drops the alpha half; using a comma instead of a slash.

Related errors

• The --alpha(…) function only accepts one argument, e.g.: `--
• The --spacing(…) function requires an argument, but received
• The --spacing(…) function requires that the `--spacing` them
• The --theme(…) function can only be used with CSS variables
• Could not resolve value for theme function: `theme(${path})`

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