{"record":{"id":"98ec1e65d19a59ce","repo":"tailwindlabs/tailwindcss","slug":"cannot-use-variant-with-variant-variant","errorCode":null,"errorMessage":"Cannot use `@variant` with variant: ${variant}","messagePattern":"Cannot use `@variant` with variant: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/tailwindcss/src/variants.ts","lineNumber":1310,"sourceCode":"          : variantNode.nodes.map(cloneAstNode),\n      )\n\n      let stackedVariants = segment(compoundVariant, ':')\n      for (let i = stackedVariants.length - 1; i >= 0; --i) {\n        let variant = stackedVariants[i].trim()\n\n        if (!variant) {\n          throw new Error(`Cannot use \\`@variant\\` with empty variant`)\n        }\n\n        let variantAst = designSystem.parseVariant(variant)\n        if (variantAst === null) {\n          throw new Error(`Cannot use \\`@variant\\` with unknown variant: ${variant}`)\n        }\n\n        let result = applyVariant(node, variantAst, designSystem.variants)\n        if (result === null) {\n          throw new Error(`Cannot use \\`@variant\\` with variant: ${variant}`)\n        }\n      }\n\n      if (node.selector === '&') {\n        nodes.push(...node.nodes)\n      } else {\n        nodes.push(node)\n      }\n    }\n\n    // Update the variant at-rule node, to be the `&` rule node\n    features |= Features.Variants\n    return WalkAction.Replace(nodes)\n  })\n  return features\n}\n","sourceCodeStart":1292,"sourceCodeEnd":1327,"githubUrl":"https://github.com/tailwindlabs/tailwindcss/blob/16e94cbf7f965c5ad697e90e940b5e178efad67c/packages/tailwindcss/src/variants.ts#L1292-L1327","documentation":"Thrown by substituteAtVariant() when applyVariant() returns null, meaning the variant parsed successfully but could not be applied to the current node. This is distinct from [85]: the variant is known, but its application to the AST node failed — typically because the variant's compound/recursive logic cannot compose with the surrounding structure.","triggerScenarios":"Using a variant whose internal resolution returns null for the given node context — e.g. a custom variant with a static() strategy that doesn't apply, or stacking variants in an order that produces no valid selector. This is the fallback when parseVariant succeeds but applyVariant's machinery yields null.","commonSituations":"Authoring a custom @custom-variant that returns no valid selector for some inputs. Combining variants in unusual stacks. Edge cases in plugin-provided variants that don't handle all node shapes. This is rarer than [85] and often indicates a variant-definition bug rather than user error.","solutions":["Simplify the variant stack: try the variant alone to isolate which combination fails.","If it is your custom variant, ensure its static/dynamic resolver always returns a valid selector (non-null).","Check the variant's definition for missing branches; report a bug if a documented built-in variant triggers this.","Try a different but equivalent variant ordering."],"exampleFix":"/* before — applyVariant returns null for this combination */\n@variant my-variant:hover { ... }\n\n/* after — verify the custom variant returns a selector */\n@custom-variant my-variant (&:where(.active));\n@variant my-variant { ... }","handlingStrategy":"try-catch","validationCode":"// Limited pre-validation; applyVariant failure is structural\n// Best: test the variant in isolation first\ndesignSystem.parseVariant(name) // ensure non-null before stacking","typeGuard":"function variantApplies(\n  node: AstNode,\n  variant: Variant,\n  variants: Map<string, Variant>\n): boolean {\n  return applyVariant(cloneAstNode(node), variant, variants) !== null\n}","tryCatchPattern":"try {\n  substituteAtVariant(ast, designSystem)\n} catch (e) {\n  if (/Cannot use `@variant` with variant:/.test(String(e))) {\n    // simplify the stack and retry, or skip the problematic rule\n  }\n}","preventionTips":["Simplify variant stacks to isolate which combination fails.","Ensure custom variants always return a valid selector.","Test variants individually before composing them."],"tags":["tailwindcss","variant","css","v4","apply-variant"],"backgroundTag":null,"analyzedSha":"16e94cbf7f965c5ad697e90e940b5e178efad67c","analyzedAt":"2026-08-12T06:02:42.469Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}