{"record":{"id":"54e075539031ec51","repo":"tailwindlabs/tailwindcss","slug":"utility-cannot-be-nested","errorCode":null,"errorMessage":"`@utility` cannot be nested.","messagePattern":"`@utility` cannot be nested\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/index.ts","lineNumber":226,"sourceCode":"          ) {\n            throw new Error('`source(…)` paths must be quoted.')\n          }\n\n          root = {\n            base: (ctx.context.sourceBase as string) ?? (ctx.context.base as string),\n            pattern: path.slice(1, -1),\n          }\n        }\n      }\n\n      utilitiesNode = node\n      features |= Features.Utilities\n    }\n\n    // Collect custom `@utility` at-rules\n    if (node.name === '@utility') {\n      if (ctx.parent !== null) {\n        throw new Error('`@utility` cannot be nested.')\n      }\n\n      if (node.nodes.length === 0) {\n        throw new Error(\n          `\\`@utility ${node.params}\\` is empty. Utilities should include at least one property.`,\n        )\n      }\n\n      let utility = createCssUtility(node)\n      if (utility === null) {\n        if (!node.params.endsWith('-*')) {\n          if (node.params.endsWith('*')) {\n            throw new Error(\n              `\\`@utility ${node.params}\\` defines an invalid utility name. A functional utility must end in \\`-*\\`.`,\n            )\n          } else if (node.params.includes('*')) {\n            throw new Error(\n              `\\`@utility ${node.params}\\` defines an invalid utility name. The dynamic portion marked by \\`-*\\` must appear once at the end.`,","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/index.ts#L208-L244","documentation":"Thrown when an `@utility` at-rule is encountered while walking the AST and the current node has a non-null parent (`ctx.parent !== null`). Tailwind requires `@utility` blocks to live at the stylesheet's top level; nesting them inside `@media`, another `@utility`, or any other rule is a structural error detected before the utility body is even parsed.","triggerScenarios":"Placing `@utility` inside `@media (...)`, inside another `@utility`, or inside any selector rule. E.g. `@media print { @utility foo { color: red } }`.","commonSituations":"Migrating component CSS where utilities were defined inside scoped blocks; tooling or preprocessors that auto-wrap rules; hand-editing a CSS file and indenting `@utility` under a media query.","solutions":["Move the `@utility` block to the top level of the stylesheet (out of any parent rule).","If you need responsive behavior, apply the variant at the call site (`print:foo`) rather than nesting the definition under `@media`.","If you were grouping utilities for organization, use comments or separate files instead of a wrapping rule."],"exampleFix":"/* before */\n@media print {\n  @utility hide-print { display: none; }\n}\n\n/* after */\n@utility hide-print { display: none; }\n/* apply via: <div class=\"print:hidden\"> — or keep print styles inside @media without @utility */","handlingStrategy":"validation","validationCode":"// Lightweight CSS walker that fails if @utility has a parent rule.\nimport postcss from 'postcss'\n\nfunction validateNoNestedUtility(css: string): string[] {\n  const errors: string[] = []\n  postcss.parse(css).walkAtRules('@utility', (rule) => {\n    if (rule.parent && rule.parent.type !== 'root') {\n      errors.push(`@utility ${rule.params} is nested under ${rule.parent.type}`)\n    }\n  })\n  return errors\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep all `@utility` blocks at column 0 of the stylesheet.","Run a pre-compile lint pass that rejects `@utility` inside any non-root parent.","Use variants at the call site (`md:foo`) instead of nesting definitions under media queries."],"tags":["at-utility","nesting","structure"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}