tailwindlabs/tailwindcss · error · Error

Could not resolve value for theme function: `theme(${path})`

Error message

Could not resolve value for theme function: `theme(${path})`. Consider checking if the variable name is correct or provide a fallback value to silence this error.

What it means

Thrown by the v4 `--theme(...)` handler when `designSystem.resolveThemeValue(path, inline)` returns a falsy value and no fallback argument was supplied. The function first checks for a fallback (`fallback.length > 0`) and returns it silently; only if there is no fallback does it throw. This is the hard-failure mode for an unknown theme variable.

Source

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

  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)

  if (!resolvedValue) {
    if (fallback.length > 0) return fallback.join(', ')
    throw new Error(
      `Could not resolve value for theme function: \`theme(${path})\`. Consider checking if the variable name is correct or provide a fallback value to silence this error.`,
    )
  }

  if (fallback.length === 0) {
    return resolvedValue
  }

  let joinedFallback = fallback.join(', ')
  if (joinedFallback === 'initial') return resolvedValue

  // When the resolved value returns `initial`, resolve with the fallback value
  if (resolvedValue === 'initial') return joinedFallback

  // Inject the fallback of a `--theme(…)` function into the fallback of a referenced `--theme(…)`
  // function or `var(…)` declaration. If the referenced function already defines a fallback, we use
  // a potential fallback value of `initial` in the referenced function to determine if we should
  // inject the fallback value of the caller. If that's not the case, we keep the fallback as-is

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Verify the variable exists in your `@theme` block or the default theme; correct the name.
2. Supply a fallback so resolution never hard-fails: `--theme(--maybe-missing, #f00)`.
3. If you intentionally cleared a default namespace, remove references to its variables from your CSS.
4. Check the v4 upgrade guide for renamed variables (e.g. `--colors-*` → `--color-*`).

Example fix

/* before */
.x { color: --theme(--color-brand-500); }
/* after */
.x { color: --theme(--color-brand-500, #3b82f6); }

// Always pass a fallback to --theme so resolution never hard-fails
// --theme(--color-brand-500, #3b82f6)
function safeThemeCall(path: string, fallback: string): string {
  return `--theme(${path}, ${fallback})`;
}

function themePathLooksValid(path: string): boolean {
  return path.startsWith('--') && /^--[a-zA-Z][\w-]*$/.test(path);
}

When it happens

Trigger: Writing `--theme(--color-does-not-exist)` with no fallback; renaming or removing a theme variable but still referencing the old name; typos in the variable name; referencing a variable defined in a different namespace that was not registered.

Common situations: Upgrading Tailwind and finding a default variable was renamed (v3 → v4 renamed many scales); disabling parts of the default theme with `--color-*: initial` but still referencing a cleared variable; typos.

Related errors

• Could not resolve value for theme function: `theme(${path})`
• 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
• The --theme(…) function can only be used with CSS variables

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