{"record":{"id":"f3c656c8081512d6","repo":"tailwindlabs/tailwindcss","slug":"the-theme-function-can-only-be-used-with-css","errorCode":null,"errorMessage":"The --theme(…) function can only be used with CSS variables from your theme.","messagePattern":"The --theme\\(…\\) function can only be used with CSS variables from your theme\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/css-functions.ts","lineNumber":94,"sourceCode":"  // - That means that a value of `1` can be replaced by `multiplier`\n  let valueDimension = dimensions.get(value)\n  if (valueDimension) {\n    if (valueDimension[0] === 0) return '0px'\n    if (valueDimension[0] === 1) return multiplier\n  }\n\n  // No known optimizations available, use full calculation\n  return `calc(${multiplier} * ${value})`\n}\n\nfunction theme(\n  designSystem: DesignSystem,\n  source: AstNode,\n  path: string,\n  ...fallback: string[]\n): string {\n  if (!path.startsWith('--')) {\n    throw new Error(`The --theme(…) function can only be used with CSS variables from your theme.`)\n  }\n\n  let inline = false\n\n  // Handle `--theme(… inline)` to force inline resolution\n  if (path.endsWith(' inline')) {\n    inline = true\n    path = path.slice(0, -7)\n  }\n\n  // If the `--theme(…)` function is used within an at-rule (e.g. `@media (width >= --theme(…)))`,\n  // we have to always inline the result since CSS does not support CSS variables in these positions\n  if (source.kind === 'at-rule') {\n    inline = true\n  }\n\n  let resolvedValue = designSystem.resolveThemeValue(path, inline)\n","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/css-functions.ts#L76-L112","documentation":"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.","triggerScenarios":"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.","commonSituations":"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`).","solutions":["Use the CSS-variable form inside `--theme`, e.g. `--theme(--color-red-500)`.","For dotted legacy paths keep using `theme(colors.red.500)` (the legacy handler) instead of `--theme(...)`.","Look up the exact variable name in your `@theme` block or the default theme reference."],"exampleFix":"/* before */\n.x { color: --theme(colors.red.500); }\n/* after */\n.x { color: --theme(--color-red-500); }","handlingStrategy":"validation","validationCode":"function assertThemePath(path: string): void {\n  if (!path.startsWith('--')) {\n    throw new Error(`--theme needs a CSS variable path, got ${JSON.stringify(path)}`);\n  }\n}","typeGuard":"function isCssVariablePath(path: string): boolean {\n  return path.startsWith('--');\n}","tryCatchPattern":null,"preventionTips":["Use --theme(--var-name) for v4 CSS-variable paths.","Use the legacy theme(dotted.path) only for backward compatibility.","Lint --theme( calls to ensure the path starts with --."],"tags":["tailwind-v4","css-function","theme","css-variables"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}