tailwindlabs/tailwindcss · error · Error

The --theme(…) function can only be used with CSS variables

Error message

The --theme(…) function can only be used with CSS variables from your theme.

What it means

Thrown by the `--theme(...)` function handler when the supplied path does not begin with `--`. In v4 theme values are exposed as CSS custom properties, so `--theme` only resolves variable-style paths (e.g. `--theme(--color-red-500)`). Passing a dotted legacy path like `colors.red.500` is invalid for the new function — that syntax belongs to the legacy `theme(...)` handler.

Source

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

  // - That means that a value of `1` can be replaced by `multiplier`
  let valueDimension = dimensions.get(value)
  if (valueDimension) {
    if (valueDimension[0] === 0) return '0px'
    if (valueDimension[0] === 1) return multiplier
  }

  // No known optimizations available, use full calculation
  return `calc(${multiplier} * ${value})`
}

function theme(
  designSystem: DesignSystem,
  source: AstNode,
  path: string,
  ...fallback: string[]
): string {
  if (!path.startsWith('--')) {
    throw new Error(`The --theme(…) function can only be used with CSS variables from your theme.`)
  }

  let inline = false

  // Handle `--theme(… inline)` to force inline resolution
  if (path.endsWith(' inline')) {
    inline = true
    path = path.slice(0, -7)
  }

  // If the `--theme(…)` function is used within an at-rule (e.g. `@media (width >= --theme(…)))`,
  // we have to always inline the result since CSS does not support CSS variables in these positions
  if (source.kind === 'at-rule') {
    inline = true
  }

  let resolvedValue = designSystem.resolveThemeValue(path, inline)

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Use the CSS-variable form inside `--theme`, e.g. `--theme(--color-red-500)`.
2. For dotted legacy paths keep using `theme(colors.red.500)` (the legacy handler) instead of `--theme(...)`.
3. Look up the exact variable name in your `@theme` block or the default theme reference.

Example fix

/* before */
.x { color: --theme(colors.red.500); }
/* after */
.x { color: --theme(--color-red-500); }

function assertThemePath(path: string): void {
  if (!path.startsWith('--')) {
    throw new Error(`--theme needs a CSS variable path, got ${JSON.stringify(path)}`);
  }
}

function isCssVariablePath(path: string): boolean {
  return path.startsWith('--');
}

When it happens

Trigger: Writing `--theme(colors.red.500)`, `--theme(spacing.4)`, or `--theme(fontFamily.sans)`. The check `!path.startsWith('--')` fails for any path not shaped like a CSS variable name.

Common situations: Migrating from v3 `theme()` calls and forgetting that v4's `--theme` wants the CSS-variable form; mixing up the legacy `theme(...)` function with the new `--theme(...)` function (both exist in `CSS_FUNCTIONS`).

Related errors

• The --alpha(…) function requires a color and an alpha value,
• The --spacing(…) function requires an argument, but received
• The --spacing(…) function requires that the `--spacing` them
• Could not resolve value for theme function: `theme(${path})`
• Could not resolve value for theme function: `theme(${path})`

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