Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 39 ยท Tooling and Build

Debugging Sass: @debug, @warn, @error and Common Errors

Debug Sass like a pro: print values with @debug, raise warnings and errors in your own code, read compiler messages, fix the most common mistakes, and inspect values with meta.inspect.

Sass runs entirely at build time, so you cannot put a breakpoint in it the way you can in JavaScript. Instead you rely on three things: messages that the compiler prints, the error output with its source excerpt, and source maps in the browser. This lesson covers all three, the errors you will meet most often, and habits that make your own mixins and functions easy for others to debug.

@debug: print a value

@debug prints a value to the terminal (or the logger) while compiling. It produces no CSS:

SCSS
$breakpoints: (sm: 40rem, md: 48rem);
@debug $breakpoints;                 // DEBUG: (sm: 40rem, md: 48rem)
@debug "width is #{math.div(100, 3)}%";

The output includes the file and line. In build tools it appears in the console that runs the build. In the browser playgrounds on this page it is hidden, because they pass a silent logger; the JavaScript lesson shows how to capture it.

Wrap a value in meta.inspect() to see its true form, which shows quotes, list brackets and map syntax that normal output hides:

SCSS
@use "sass:meta";
@debug meta.inspect(("a", b, 3px));   // ("a", b, 3px)
@debug meta.type-of($value);          // number, string, list, map, color, bool, null

A handy debug mixin for maps prints every pair on its own line:

SCSS
@mixin debug-map($map) {
  @each $key, $value in $map {
    @debug "#{$key}: #{meta.inspect($value)}";
  }
}

@warn: tell the caller something is wrong, but continue

@warn prints a message with a stack trace showing who called the mixin or function. The compilation continues. Use it for deprecations and soft problems in your own library:

SCSS
@mixin old-button {
  @warn "old-button is deprecated, use button instead.";
  @include button;
}

If the message always appears, people stop reading it. Warn only when something genuinely needs attention, and say what to do instead.

@error: stop the build

@error ends compilation with a message. Use it to reject invalid arguments early, with an explanation, instead of letting a confusing failure appear three levels deeper:

SCSS
@use "sass:map";
@use "sass:meta";

@function z($layer) {
  $layers: (modal: 100, dropdown: 50, base: 1);
  @if not map.has-key($layers, $layer) {
    @error "Unknown z-index layer `#{$layer}`. Choose from: #{map.keys($layers)}.";
  }
  @return map.get($layers, $layer);
}

@mixin size($w, $h: $w) {
  @if meta.type-of($w) != "number" {
    @error "size() expects a number, got #{meta.inspect($w)} (#{meta.type-of($w)}).";
  }
  width: $w;
  height: $h;
}

Good error messages name the argument, show the bad value, and list valid choices. The playground below shows how the compiler reports an error: the message, the source line with a pointer, and the stack of calls.

An @error with a helpful message

The compiled CSS area shows the error. Fix the typo (dropdown) and the CSS appears.

Reading an error message

A Sass error has four parts:

TEXT
Error: Undefined variable.
  โ•ท
3 โ”‚   color: $primray;
  โ”‚          ^^^^^^^^
  โ•ต
  src/_button.scss 3:10  @use
  src/main.scss 1:1      root stylesheet
  1. The message (Undefined variable.): what went wrong.
  2. The excerpt: the offending line, with carets under the exact span.
  3. The stack: file, line and column, innermost first. For code inside a mixin the stack lists the mixin and then where it was included, so you can find both the definition and the use.
  4. In the JavaScript API, the same data is on the exception: sassMessage, span, sassStack.

Read from the top, then follow the stack to your code rather than a library's.

The most common errors

Message Usual cause Fix
Undefined variable. Typo, wrong scope, or missing namespace after @use Write tokens.$brand; check spelling
Undefined mixin. / Undefined function. Missing @use or namespace @include buttons.base
Can't find stylesheet to import. Wrong path, missing load path Check name, underscore, folder, --load-path
@use rules must be written before any other rules. @use after a style rule Move all @use to the top
1px and 1s have incompatible units. Adding or comparing unlike units Convert units or use calc()
A top-level selector may not contain a parent selector with a suffix. &-name or &__x written outside any rule Move it inside a rule
Expected expression. A declaration with no value, or a stray operator Check the line above the pointer
This module was already loaded, so it can't be configured using "with". Configuring after an earlier @use Configure on the first @use only
Deprecation [slash-div]: using / for division Writing $a / $b math.div($a, $b)
expected end of rule. A missing closing brace earlier in the file Count braces

A syntax error is usually reported on the line after the real mistake, because that is where the parser noticed. Look one or two lines up.

When an error points into a huge file, comment out half of the @use lines in main.scss and compile again. Binary search finds the broken partial in a few steps.

Unit and type mistakes

Sass checks units. 10px + 5em is an error; 10px + 5 yields 15px (a unitless number adopts the unit); multiplying two lengths (10px * 5px) gives a compound unit that CSS cannot use, so do the math on plain numbers and add the unit at the end. To combine incompatible units, use calc(): calc(100% - #{$gutter}). Interpolate Sass values inside calc() so they are evaluated first.

SCSS
$gutter: 2rem;
.sidebar { width: calc(100% - #{$gutter}); }

Check types with meta.type-of() when a function misbehaves: a value read from a map may be a string ("10px") rather than a number, and string math fails.

Deprecation warnings

Newer compilers print deprecation warnings for features scheduled for removal, with an id in brackets:

TEXT
DEPRECATION WARNING [import]: Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0.
DEPRECATION WARNING [global-builtin]: Global built-in functions are deprecated...
DEPRECATION WARNING [slash-div]: Using / for division outside of calc() is deprecated...

Handle them deliberately instead of ignoring them:

  • Fix them. The message usually suggests the replacement (color.adjust for darken, math.div for /, @use for @import). See migrating from @import.
  • While migrating, --silence-deprecation=import or quietDeps: true hides noise from third-party code you cannot change yet.
  • In CI, --fatal-deprecation=<version> fails the build if code uses anything deprecated by that version, so new violations cannot slip in.

Debugging in the browser

Source maps connect CSS rules to Sass files and lines (CLI and source maps). In DevTools, inspect an element, click the filename link on a rule, and you land in the right .scss partial. If the styles panel shows plain main.css lines, the map is not loaded (not served, or the sourceMappingURL comment is missing).

To see which Sass produced a surprising selector, temporarily emit the compiled CSS in expanded style and search for the class name. Selectors built with & suffixes and @each do not appear literally in the source, so searching the output is the reliable way.

Linting and automatic checks

  • stylelint with stylelint-config-standard-scss flags invalid syntax, duplicate selectors, too much nesting and unknown at-rules.
  • A CI step that compiles with --fatal-deprecation and no --quiet catches problems before a deploy.
  • Write tiny unit tests for functions with sass-true or by asserting compiled output in a script. A test is a few lines: compile a string, compare the CSS.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the difference between @warn and @error?

    A warning is informational; an error ends the build.
  2. 2. Which tool shows the exact type of a value, including list brackets and quotes?

    meta.inspect returns the value's source-like form and type-of returns its type name.
  3. 3. A syntax error points at line 12. Where should you also look?

    The parser often detects the problem on the line after the real mistake.
  4. 4. How do you subtract a Sass variable from 100% in CSS?

    Incompatible units need calc(); interpolation evaluates the variable first.
  5. 5. What does --fatal-deprecation do in CI?

    It enforces migration by making deprecated usage a failure.

Summary

  • @debug prints values, @warn prints a message and continues, @error stops the build; write errors that name the argument, the bad value and the valid choices.
  • A Sass error has a message, a source excerpt, and a stack of calls; read the top, then follow the stack to your code.
  • Learn the common errors: undefined names after @use, missing load paths, @use order, unit mismatches, / division, configuring a loaded module.
  • Treat deprecation warnings as to-do items; use quietDeps, --silence-deprecation and --fatal-deprecation deliberately.
  • Source maps, stylelint and small output tests make problems visible early.

Next: Migrating from @import to @use