{"record":{"id":"6cfa34f06effc947","repo":"Textualize/textual","slug":"reference-to-undefined-variable-variable-name","errorCode":null,"errorMessage":"reference to undefined variable '${variable_name}'; did you mean '${suggested_variable}'?","messagePattern":"reference to undefined variable '(.+?)'; did you mean '(.+?)'\\?","errorType":"validation","errorClass":"UnresolvedVariableError","httpStatus":null,"severity":"error","filePath":"src/textual/css/parse.py","lineNumber":359,"sourceCode":"\n\ndef _unresolved(variable_name: str, variables: Iterable[str], token: Token) -> NoReturn:\n    \"\"\"Raise a TokenError regarding an unresolved variable.\n\n    Args:\n        variable_name: A variable name.\n        variables: Possible choices used to generate suggestion.\n        token: The Token.\n\n    Raises:\n        UnresolvedVariableError: Always raises a TokenError.\n    \"\"\"\n    message = f\"reference to undefined variable '${variable_name}'\"\n    suggested_variable = get_suggestion(variable_name, list(variables))\n    if suggested_variable:\n        message += f\"; did you mean '${suggested_variable}'?\"\n\n    raise UnresolvedVariableError(\n        token.read_from,\n        token.code,\n        token.start,\n        message,\n        end=token.end,\n    )\n\n\ndef substitute_references(\n    tokens: Iterable[Token], css_variables: dict[str, list[Token]] | None = None\n) -> Iterable[Token]:\n    \"\"\"Replace variable references with values by substituting variable reference\n    tokens with the tokens representing their values.\n\n    Args:\n        tokens: Iterator of Tokens which may contain tokens\n            with the name \"variable_ref\".\n","sourceCodeStart":341,"sourceCodeEnd":377,"githubUrl":"https://github.com/Textualize/textual/blob/06dbeef4bb70fb718236aa418ed658ef4667a126/src/textual/css/parse.py#L341-L377","documentation":"During CSS variable substitution (substitute_references), Textual resolves $variable references against defined variables. An undefined reference raises UnresolvedVariableError with source position; if a similarly named variable exists, get_suggestion appends a 'did you mean' hint.","triggerScenarios":"`$accnet` in a tcss when only `$accent` is defined; using `$var` defined in a different scope/component; typos or renaming a variable without updating all usages.","commonSituations":"Renaming design-token variables and missing call sites; referencing variables defined in another widget's CSS; upgrading a theme where a variable was removed.","solutions":["Use the suggested variable from the 'did you mean' hint if present","Define the variable with `$name: value;` in the same CSS (or a higher DEFAULT_CSS) before use","Search all .tcss/py CSS strings for the exact $reference after renames"],"exampleFix":"/* before */\n$accnet: ansi_red;\nbackground: $accnet;\n/* after */\n$accent: ansi_red;\nbackground: $accent;","handlingStrategy":"validation","validationCode":"import re\nrefs = set(re.findall(r\"\\$([\\w-]+)\", css_text))\ndefined = set(re.findall(r\"\\$([\\w-]+)\\s*:\", css_text))\nmissing = refs - defined\nassert not missing, missing","typeGuard":null,"tryCatchPattern":"from textual.css.errors import UnresolvedVariableError\ntry:\n    ...\nexcept UnresolvedVariableError as e:\n    # e.g. add the variable or fix the reference","preventionTips":["Centralize variable definitions and lint $references against them after renames"],"tags":["textual","css","variables","undefined-variable"],"backgroundTag":"undefined-variable-reference","analyzedSha":"06dbeef4bb70fb718236aa418ed658ef4667a126","analyzedAt":"2026-08-27T02:36:57.214Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}