tailwindlabs/tailwindcss · error · Error

Files imported with `@import "…" theme(reference)` must only

Error message

Files imported with `@import "…" theme(reference)` must only contain `@theme` blocks.
Use `@reference "…";` instead.

What it means

Thrown while processing an `@import "..." theme(reference)` (or any `theme(...)` import that includes `reference`) when the imported file contains any node that is not an `@theme` at-rule. Reference-theme imports are a special narrow channel for pulling in design tokens, so non-theme content (rules, declarations, other at-rules) is rejected with a pointer to `@reference` as the correct alternative.

Source

Thrown at packages/tailwindcss/src/index.ts:492

          })
        }

        // Handle `@media theme(…)`
        //
        // We support `@import "tailwindcss" theme(reference)` as a way to
        // import an external theme file as a reference, which becomes `@media
        // theme(reference) { … }` when the `@import` is processed.
        else if (param.startsWith('theme(')) {
          let themeParams = param.slice(6, -1)
          let hasReference = themeParams.includes('reference')

          walk(node.nodes, (child) => {
            if (child.kind === 'context') return
            if (child.kind !== 'at-rule') {
              if (hasReference) {
                throw new Error(
                  `Files imported with \`@import "…" theme(reference)\` must only contain \`@theme\` blocks.\nUse \`@reference "…";\` instead.`,
                )
              }

              return WalkAction.Continue
            }

            if (child.name === '@theme') {
              child.params += ' ' + themeParams
              return WalkAction.Skip
            }
          })
        }

        // Handle `@media prefix(…)`
        //
        // We support `@import "tailwindcss" prefix(ident)` as a way to
        // configure a theme prefix for variables and utilities.
        else if (param.startsWith('prefix(')) {
          let prefix = param.slice(7, -1)

View on GitHub (pinned to 16e94cbf7f)

Solutions

1. Move only the `@theme { ... }` block(s) into the imported file and keep other CSS elsewhere.
2. If you want to import non-theme CSS without it contributing candidates, use `@reference "...";` instead of `theme(reference)`.
3. Audit the imported file with the error's walk logic in mind: every top-level node must be an `@theme` at-rule (comments and `context` nodes are allowed; everything else is rejected).

Example fix

/* before — tokens.css mixes theme + base */
@theme { --color-brand: #007; }
body { margin: 0; }
/* main.css */
@import "./tokens.css" theme(reference);

/* after — tokens.css contains only @theme */
@theme { --color-brand: #007; }
/* main.css: use @reference for non-theme CSS */
@reference "./base.css";

// Before importing a file as theme(reference), verify it contains only @theme (and comments).
import postcss from 'postcss'

async function validateReferenceThemeFile(content: string): Promise<string[]> {
  const errors: string[] = []
  const root = postcss.parse(content)
  root.each((node) => {
    if (node.type === 'comment') return
    if (node.type === 'atrule' && (node as postcss.AtRule).name === 'theme') return
    errors.push(`Non-@theme node of type ${node.type} is not allowed in a theme(reference) import`)
  })
  return errors
}

When it happens

Trigger: Importing a CSS file via `@import "./tokens.css" theme(reference);` where `tokens.css` contains selectors, plain rules, or at-rules other than `@theme`.

Common situations: Migrating a tokens file that also contains base styles or component CSS; misunderstanding that `theme(reference)` is strictly for theme variables.

Related errors

• Exceeded maximum recursion depth while resolving `${uri}` in
• `layer(…)` in an `@import` should come before any other func
• The prefix "${resolvedConfig.prefix}" is invalid. Prefixes m
• `addVariant('${name}')` defines an invalid variant name. Var
• `matchUtilities({ '${name}' : … })` defines an invalid utili

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