Using Sass’s @error, @warn, and @debug Directives

James Steinbach
James Steinbach
Share

Feedback methods are essential in any programming language. In JavaScript, you’ve probably used console.log() or maybe alert(). In PHP, you can use var_dump() or print_r(). In Ruby, you may use debug or inspect. All these functions allow you to debug any value and find out what your code is doing at any point in the logic where you need help.

Sass has three directives for providing feedback to developers. They are @error, @warn, and @debug. In this post, we’ll look at how to use these directives, what use cases they’re best suited for, and what kind of feedback they can provide for other developers who use our code.

Basic Syntax and Use

All three of these directives follow the same syntax:

@directive "String of text to output.";

Well, that’s not entirely true. The three directives expect anything, not necessarily a string. This means you can warn, throw, or debug a map, a list, a number, a string — basically anything you want. However, as we often use these directives to give some context on the problem, we’ll usually pass a string that describes the situation.

If you need to interpolate a variable’s value in that string, you can do so using the standard Sass interpolation (#{$variable}) and the value will be printed in the string. With this method, you can tell a developer both the name of the variable and its current value:

@error "Sorry, but `#{$variable}` is not a valid value for $variable.";

Note that the ticks (`) around the interpolation are not required. You may want to include them because they give the developer an obvious start/stop point for the variable’s contents.

If a developer makes a mistake when using your Sass code, these directives will send the specified message to the compiler and the compiler will show that message to the developer. For example, GUI apps (like CodeKit) will show a system notification with the error. Certain Grunt and Gulp notification packages can do that as well.

If a developer is compiling with the command line (Sass, Compass, Grunt, or Gulp), the message will likely end up in their console (Terminal, iTerm2, Putty, etc). If you’re writing Sass online with Sassmeister or Codepen, you’ll only get limited feedback, but you may get an inline notification in your editor or text in the output window.

Now that we know how to write @error, @warn, and @debug messages and where they’ll appear for the developer, let’s look at the difference between these directives and the best uses for each one.

Stop Everything – The @error Directive

Sass’s @error directive stops the Sass compiler completely and sends its string of text to the compiler’s output as a fatal error. Use this directive when you need to send a message that stops the developer immediately and forces them to correct their mistake right away. This is ideal for letting a developer know they’ve done something wrong or entered a value that’s entirely incompatible. Sass will include the line number with any fatal error, including @error output. The @error directive is ideal for validating arguments within a mixin or function.

Note: If your compiler is older than Sass 3.4 or LibSass 3.1, @error is not available. You can use this log() function to emulate @error in older Sass versions.

As an example, if you’ve written a function that relies on a certain input format for its calculations, you can validate the input and use @error to stop the compiler and alert the developer that they’ve made a mistake that can’t be overlooked. If you’ve written a function that relies on a key/value pair from a map, @error can make sure that the key that’s called from the map actually exists.

This Sass color management tool uses @error to ensure that the developer only uses a color name that’s a valid CSS color name or a key from a related map:

Map:

$colors: (
  brand-red: #c0392b,
  brand-blue: #2980b9,
  text-gray: #2c3e50,
  text-silver: #bdc3c7
);

Function (simplified for the sake of brievity):

@function color-variation($color) {
  @if map-has-key($colors, $color) {
    @return map-get($colors, $color);
  }
  
  @error "Invalid color name: `#{$color}`.";
}

Usage:

.element {
  color: color-variation(brand-orange);
}

Output:

>> Invalid color name: `brand-orange`.
>>   Line 9  Column 7  sass/test.scss

In this example, if the developer tries calling the color-variation() function with a string that’s neither a valid CSS color nor a key from the $colors map, there’s nothing Sass can do to output a valid color. Using @error gives the developer specific, actionable feedback.

Don’t Miss This – The @warn Directive

The @warn directive is considerably less severe than @error. It sends its message to the compiler for the developer to read, but it allows the compiler to finish its job and write all the CSS. While @error is good for correcting an error that breaks a function or mixin entirely, @warn is better suited for deprecation notices, or suggesting a developer follow certain best practices.

Note: Sass developers who use the --quiet flag when they compile will not see @warn output. If the developer absolutely needs to see the feedback your Sass is sending, rely on @error. It’s rare for @warn to be turned off, but it is possible.

Sass will also include a line number with @warn output to help the developer find and improve any code that needs to be edited. For example, you may have a library full of mixins, and you plan to deprecate several of the mixins in a future release. One way to help your developers prepare for that change is to @warn them about the upcoming deprecation:

// No one should ever prefix border-radius properties ;)
// so let's deprecate this from our imaginary library:

@mixin border-radius($radius) {
  @warn "The `border-radius()` mixin will be deprecated in version 2.0.";

  -webkit-border-radius: $radius;
  -moz-border-radius: $radius;
  -ms-border-radius: $radius;
  -o-border-radius: $radius;
  border-radius: $radius;
}

Output:

WARNING: The `border-radius()` mixin will be deprecated in version 2.0.
  on line 2 of sass/test.scss
  from line 21 of sass/test.scss

You can see this in action in this deprecation partial from Bourbon Sass.

Another good use case for @warn is enforcing team code standards. You might write a function that can successfully handle input in both pixels or rem units, but you might prefer everyone on your team uses rems. Here’s an example of @warn to help your coworkers follow that standard:

@function do-math($input) {
  @if unit($input) == "px" {
    @warn "Please remember to use rem values in the `do-math()` function.";
    // do px math and @return a value to prevent the function from going any further
  }
  
  // do rem math and @return a value
}

Output:

WARNING: Please remember to use rem values in the `do-math()` function.
  on line 3 of sass/test.scss
  from line 12 of sass/test.scss

If You Were Curious – The @debug Directive

Sass’s @debug directive is the least intrusive of all three feedback directives. It prints the value of whatever Sass expression it contains (variable, math, etc.) to the console for the developer. It’s not entirely useful in open source or team libraries. Rather, @debug is ideal for personal debugging work. If you’re in a complex bit of math and need to know what one of your variables contains at the moment, use @debug to find out.

Usage:

$color-blue: #1c94c6;
$font-sizes: sm, p, bq, heading, hero;
$colors: (
  brand-red: #c0392b,
  brand-blue: #2980b9,
  text-gray: #2c3e50,
  text-silver: #bdc3c7
);

.element {
  @debug $color-blue; // single value
  @debug $font-sizes; // list
  @debug $colors; // map
  @debug 4em * 3; // math expression
  @debug "My very own string just because."; // string
}

Output:

sass/test.scss:5: DEBUG: #1c94c6
sass/test.scss:6: DEBUG: sm, p, bq, heading, hero
sass/test.scss:7: DEBUG: (brand-red: #c0392b, brand-blue: #2980b9, text-gray: #2c3e50, text-silver: #bdc3c7)
sass/test.scss:8: DEBUG: 12em
sass/test.scss:9: DEBUG: My very own string just because.

Conclusion

Programming in a black hole without feedback would be awful. Fortunately, Sass has multiple directives that can send feedback to the compiler to help developers avoid mistakes, maintain standards, and troubleshoot advanced logic. You can use @error, @warn, and @debug to provide time-saving feedback for yourself and for any others who use your code.

Do you have any creative uses for these directives? Share them in the comments!

Frequently Asked Questions (FAQs) about Using Sass Error, Warn, and Debug Directives

What is the purpose of using Sass directives such as error, warn, and debug?

Sass directives like error, warn, and debug are used to help developers identify and fix issues in their Sass code. The error directive stops the compilation process and displays an error message, making it useful for highlighting critical issues that need immediate attention. The warn directive, on the other hand, displays a warning message but doesn’t stop the compilation, making it ideal for less critical issues. The debug directive is used to output the value of Sass expressions to the console, which can be helpful in troubleshooting and understanding how your code is being processed.

How do I use the error directive in Sass?

To use the error directive in Sass, you simply need to write @error followed by your custom error message in quotes. For example, @error “This is a custom error message”. When Sass encounters this directive during the compilation process, it will stop and display your custom error message.

How can I view the output of the debug directive?

The output of the debug directive can be viewed in the console where you run your Sass compiler. When the debug directive is encountered during the compilation process, it will output the value of the Sass expression to the console. This can be very helpful in understanding how your Sass code is being processed and identifying any potential issues.

Can I use the warn and debug directives in a Rails project?

Yes, you can use the warn and debug directives in a Rails project. The output of these directives can be viewed in the Rails server console. This can be very helpful in identifying and fixing issues in your Sass code.

How can I handle validation error messages using directives in Angular?

While this is a bit outside the scope of Sass, Angular does provide a way to handle validation error messages using directives. You can create a custom directive that checks the validity of form inputs and displays appropriate error messages. This can be a powerful way to provide immediate feedback to users and improve the user experience.

What happens if I use the error directive in a production environment?

If you use the error directive in a production environment, it will stop the Sass compilation process and display an error message. This can cause your stylesheets to not be generated correctly, which can lead to issues with the appearance of your website. Therefore, it’s generally recommended to only use the error directive during development and testing.

Can I use the warn and debug directives to log information to a file?

The warn and debug directives output their messages to the console, not to a file. However, you can redirect the console output to a file if you wish. This can be done using the command line redirection operators > and >>.

Can I use the error, warn, and debug directives with other preprocessor languages like Less or Stylus?

The error, warn, and debug directives are specific to Sass and are not available in other preprocessor languages like Less or Stylus. However, these languages may have their own mechanisms for error handling and debugging.

Can I use the error, warn, and debug directives in Sass libraries and mixins?

Yes, you can use the error, warn, and debug directives in Sass libraries and mixins. This can be very helpful in identifying and fixing issues in these reusable pieces of code.

Can I customize the messages displayed by the warn and debug directives?

Yes, you can customize the messages displayed by the warn and debug directives. You simply need to write @warn or @debug followed by your custom message in quotes. For example, @warn “This is a custom warning message” or @debug “This is a custom debug message”.