Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 39 ยท Control Directives and Maps

Debugging Sass with @debug, @warn and @error

Find and fix Sass problems: print values with @debug, raise warnings and errors in your own code, capture messages with a logger, handle deprecations and read common error messages.

Sass runs entirely at compile time, so there is no browser console to peek into. When a calculation comes out wrong or a mixin receives a surprising value, you need another way to look inside. Sass gives you three built-in messages for that, plus good error output and a few habits that make problems easy to find. This lesson also finishes the chapter on control directives, since debugging often means checking what a loop or condition actually did.

The three message directives

Directive What it does Stops compilation?
@debug expr; Prints the value of an expression, with the file and line No
@warn expr; Prints a warning with a stack trace of where it was triggered No
@error expr; Prints an error with a stack trace and stops Yes
SCSS
$gap: 8px * 3;
@debug "gap is #{$gap}";      // Debug: gap is 24px
@warn "Using the old API.";   // Warning: ...
@error "Not supported.";      // Error: stops here

Messages appear in the terminal that runs Sass, not in the CSS. Anything can be printed: strings, numbers, lists, even maps (@debug $theme; prints the whole map, which is a quick way to read a nested structure).

@debug for inspection

Use it like console.log. A couple of habits help:

  • Prefix the message with a label: @debug "breakpoints:" $breakpoints; is easier to find than a naked value. (Commas are not allowed between values, so use interpolation for several: @debug "w=#{$w} h=#{$h}";.)
  • Remove the @debug lines before committing. A library that prints debug output on every build is annoying.
  • Combine with meta.inspect($value) or meta.type-of($value) when you are unsure what you have.

@warn for soft problems

@warn is for things the author of the stylesheet should fix but that do not make the output wrong: using a deprecated mixin, passing an unusual value, or relying on a default that will change. Libraries use it to announce deprecations:

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

@error for contract violations

@error is for inputs that must be fixed, such as an unknown breakpoint or a missing token. It stops compilation immediately and shows the message and the call chain. You saw it in custom functions and in maps. A good error message says what was wrong, what was received and what is allowed:

SCSS
@error "Unknown size `#{$size}`. Expected one of: #{map.keys($sizes)}.";
Capture @debug, @warn and @error

In the demo the JavaScript logger option captures every @debug and @warn. On the command line the messages go to standard error. Tools like webpack's sass-loader and Vite also print them in the build output.

Reading error messages

Sass errors show the message, the offending source lines with an underline, and a stack trace of includes and calls. The ones you will meet most often:

Message Usual cause
Undefined variable. Typo, wrong scope, or missing module. prefix
Undefined mixin. / Undefined function. Typo, or the module was not loaded with @use
Incompatible units px and em. Adding, subtracting or comparing unlike units
Expected ";" / expected "}" Missing semicolon or brace before the underlined spot
This module was already loaded, so it can't be configured using "with". @use ... with came after another @use of the same module
Can't find stylesheet to import. File name, load path or missing underscore partial
... isn't a valid CSS value. Printing a map or function value; use meta.inspect()
Top-level selectors may not contain the parent selector "&". & used outside a rule

Always look at the line the error points to and the line before it: a missing semicolon is reported at the next token.

Deprecation warnings

When Sass changes a feature it first prints a deprecation warning that names the feature, explains the replacement and links to a page about it. You have seen several in this tutorial: / as division, global color functions, @import, the comma form of if().

  • Fix them as you see them; deprecations are removed in the next major version.
  • Warnings that come from third-party packages in node_modules can be silenced with --quiet-deps (or quietDeps: true).
  • You can silence one specific deprecation while you migrate with --silence-deprecation=import, or turn warnings into build failures in CI with --fatal-deprecation= followed by a version or id.
  • sass-migrator automatically rewrites several deprecated patterns (@import to @use, division to math.div).

Run the demo below to see two of them reported as they happen.

Silencing and counting deprecations

The output is identical either way: a deprecation warning does not change the CSS, it only tells you the code will need a change. The ids it prints (here global-builtin and color-functions) are what you pass to --silence-deprecation. sass.Logger.silent hides everything, which is handy for tests but risky in real builds.

Debugging strategies that work

  1. Look at the compiled CSS first. It shows what Sass actually produced. If a rule is missing, check the condition; if there are too many, check the loop.
  2. Shrink the problem. Copy the failing mixin and its input into a new file and call it directly.
  3. Print with @debug, including meta.type-of() when a value surprises you, for example a string where you expected a number.
  4. Check scope. Did you assign in a block (a new local) or use !global?
  5. Check the namespace. Errors about missing members are most often a forgotten module. prefix.
  6. Use source maps in the browser: they show the original SCSS file and line for every rule.
  7. Assert in your own code. Validate arguments with @error so mistakes fail loudly near their cause.

Treat @debug like a temporary tool and @warn/@error as permanent parts of a public API. Libraries without good errors force every user to debug by guessing.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which directive stops compilation?

    @error stops and reports a failure. @debug and @warn print a message and continue.
  2. 2. Where does @debug output appear?

    Messages go to the compiler's logger. The CSS is unchanged.
  3. 3. What is a good use of @warn?

    @warn is for problems the author should fix that do not make the output wrong. Use @error to reject invalid input.
  4. 4. How do you print a map's contents in a CSS property while debugging?

    Maps are not valid CSS values. meta.inspect() converts any value to its text form.

Summary

  • @debug prints a value, @warn prints a warning and continues, @error prints an error and stops.
  • Messages go to the compiler's logger, which the JavaScript API lets you capture with the logger option.
  • Read errors from the underlined line and the one before it; learn the common messages in the table.
  • Deprecation warnings point to replacements; migrate rather than silence, except for dependencies.
  • Inspect values with meta.inspect() and meta.type-of(), and validate inputs with @error.

Next: Modules: @use and @forward