Why Your SCSS Variable Is Undefined and How to Fix It

Dart Sass introduced @use and @forward as replacements for the long-deprecated @import rule. The fundamental difference is that @use does not pollute the global namespace. When you write @use 'variables', Sass makes that file's contents available under the variables. namespace. Every variable, mixin, and function from that file must be accessed as variables.$my-var rather than just $my-var. This is intentional — it makes it immediately clear which file a value comes from.

The deprecation of @import happened gradually. LibSass and older versions of node-sass still supported @import without warnings, so many codebases continued using it. When a project upgrades to Dart Sass 1.23 or later (which ships with modern bundlers like Vite, webpack 5, and Next.js), the existing @import statements generate deprecation warnings, and in Dart Sass 2.x they will become hard errors.

The most common migration mistake is adding @use without updating the variable references. A developer changes @import 'variables' to @use 'variables' and immediately gets undefined variable errors on every $primary, $spacing-*, and $font-* reference in the file. The fix is to either add the namespace prefix to each reference or to use the wildcard @use 'variables' as * — but the wildcard should be reserved for small files where namespace clarity is less important.

There is a second, subtler issue with @use: a file can only be used once per module graph. If two files both @use 'theme', Dart Sass loads the module once and shares it. This is efficient but it means you cannot use !default overrides in two different consuming files. Overrides must happen before any @use statement, typically in an entry file using @use 'theme' with ($primary: red).

Start with the compiler output. Dart Sass prints the file path and line number where the undefined variable was referenced, as well as any stack frames showing which @use or @forward chain led to that point. The error message will say something like: Error: Undefined variable. with the variable name and the line number. Read the message carefully — it tells you exactly where the reference failed, not where the variable should be defined.

Open your browser's DevTools (F12) and check the Sources panel or the CSS pane. If Sass source maps are enabled, clicking on a style in the Elements panel will take you to the original .scss file and line. This is helpful for confirming that a compiled stylesheet is missing a rule entirely — which happens when a variable is undefined and the entire block fails to compile.

At the terminal, run your Sass CLI with verbose output. For Dart Sass: sass --watch src/styles:public/css --no-source-map. The output will include the load order of @use statements, which lets you trace which files are being resolved and in what order. If a file is listed twice in the stack trace under @use, there may be a circular dependency.

For larger projects, search your codebase for the failing variable name. Confirm it is defined at the top level (not inside a selector), that the file containing it is a partial (filename starts with underscore), and that the consuming file uses @use 'filename' with the correct relative path. Many projects use a barrel file like _index.scss with @forward rules to re-export variables from multiple partials — verify your entry file uses that barrel.

If the error is a missing namespace: add the filename prefix to every variable reference. If you had @import 'variables' and referenced $primary, change the import to @use 'variables' and every reference to variables.$primary. Use your editor's find-and-replace to do this systematically across the file rather than hunting for each one manually.

If the variable is defined inside a selector block: cut the declaration and paste it at the top of the file, before any selector. Variables at file level are accessible from any selector in that same file. If other files also need the variable, move it to a dedicated partial like _tokens.scss and add @use 'tokens' to each consuming file.

If you want to avoid namespacing entirely — common when migrating a large codebase — use @use 'variables' as * in each file. This makes all variables from that module available without a prefix, mimicking the old @import behavior. It is not recommended for new code because it obscures where values come from, but it is a valid short-term migration strategy.

If the issue is with !default overrides: configuration must happen in a single dedicated entry file. Create a _config.scss that defines your override values, then use @use 'variables' with ($primary: $my-override-primary) in that config file. Other files should @use 'config' rather than @use 'variables' directly. This ensures overrides are applied before any module resolves its defaults.

After any fix, recompile the full stylesheet rather than just the changed file. In watch mode, Dart Sass may cache a stale module state. Kill the watch process and restart it to force a clean compile.

Partial files must start with an underscore: _variables.scss, _mixins.scss, _tokens.scss. When you write @use 'variables', Sass resolves it to _variables.scss in the same directory. If you accidentally name your file variables.scss without the underscore, Sass will attempt to compile it as a standalone output file and may fail to resolve it as a module, or will compile it to an unwanted variables.css file.

The @forward rule is commonly misunderstood. @forward makes the contents of a module available to any file that @uses the file containing the @forward. It does not make them available inside the file itself. A barrel file _index.scss might contain @forward 'variables'; @forward 'mixins'; — consuming files then @use 'styles/index' and get access to everything forwarded. If you try to use a forwarded variable inside the barrel file itself, you will get an undefined error.

Mixins and functions that reference variables resolve at definition time, not call time. A mixin defined in _mixins.scss that references a variable from _variables.scss must @use 'variables' itself. It cannot rely on the calling file to have already loaded those variables. This is a common mistake when converting a flat @import-based stylesheet into a modular @use architecture.

If you are using Tailwind alongside SCSS, note that PostCSS and Dart Sass are entirely separate compilation pipelines. Variables defined in SCSS are not available inside Tailwind's @apply rules, and CSS custom properties defined at runtime are not the same as SCSS compile-time variables. They serve different purposes and cannot be used interchangeably across pipelines.

The single biggest migration mistake is doing a bulk find-and-replace of @import with @use without also updating variable references. The files will load without syntax errors, but every variable reference will fail at runtime with an undefined error because the namespace prefix is missing. Always update the references in the same step as the import statement.

Another common mistake is using @use after other rules in a file. The @use rule must appear before any other statements except @charset. Dart Sass enforces this strictly. If you have a @mixin definition or a CSS rule before your @use statement, you will get an error about @use not being allowed after other rules. The fix is to move all @use and @forward declarations to the very top of the file.

Developers sometimes try to use @use inside a mixin or a conditional. This is not allowed — @use is a static declaration and must be at the top level of the file. If a mixin needs access to variables from another file, add @use at the top of the file that contains the mixin, not inside the mixin body.

In React and Vue projects with CSS Modules, each .module.scss file is compiled independently. A variable defined in one module is not available in another without @use. A common mistake is defining $brand-color in a component stylesheet and expecting it to be available in a sibling component. Always extract shared variables to a partial and @use it explicitly in each component that needs it.

Structure your SCSS around a dedicated design token file. Name it _tokens.scss or _variables.scss and place it at the root of your styles directory. Define every color, spacing value, font size, border radius, and z-index here. Every other file that needs these values adds @use '../tokens' as t at the top. This creates a single source of truth and makes it trivially easy to trace where any value comes from.

Use a barrel file to simplify imports in large projects. Create _index.scss in each directory and populate it with @forward rules pointing to every partial in that directory. Consuming files then need only one @use statement per directory rather than one per file. Keep barrel files free of variable declarations and rule blocks — their only job is forwarding.

Add Stylelint with the stylelint-scss plugin to your project. Configure it to warn on @import usage and to enforce consistent namespace usage. Running Stylelint in CI catches undefined variable errors before they reach production. The no-global-function-names rule and the at-use-no-unnamespaced rule are especially useful during @import to @use migrations.

Document your namespace conventions in the project README. If your team decides to use @use 'tokens' as t everywhere, note that decision explicitly. Inconsistent aliasing — some files using @use 'tokens' as t, others using @use 'tokens' as tok, and others using @use 'tokens' as * — makes the codebase harder to navigate and increases the chance of future undefined variable errors.

For teams adopting a formal SCSS architecture, the 7-1 pattern is a proven structure that organises partials into seven folders (abstracts, base, components, layout, pages, themes, vendors) with a single main.scss entry file that forwards them all in a defined order. This structure makes variable scope and import order predictable because each category of partial has a designated folder and loading sequence, eliminating the ambiguity about which partial should @forward which variables and ensuring tokens are always available before the rules that consume them.