How to Use Warnings and Errors in Sass Effectively

Original Source:

The following is a short extract from our book, Jump Start Sass, written by Hugo Giraudel and Miriam Suzanne. It’s the ultimate beginner’s guide to JavaScript. SitePoint Premium members get access with their membership, or you can buy a copy in stores worldwide.

Our incredible journey through Sass is slowly coming to an end, and so far you’ve been doing great! There’s one technical chapter left before we look at project architecture, and then you’ll be fully equipped to write Sass code in your own projects.

Now we’re going to look at warnings and errors. Both form a one-way communication system between the program (in this case, Sass) and the developer (you). If you’re wondering about the point of errors in the CSS world, remember that you already know the answer. Whenever you forget a semicolon or use a function incorrectly, Sass throws an error at you, explaining what you’ve done wrong and how you can fix it, thankfully! It would be a real pain to have to dig into the code to figure out what’s gone wrong.

Sass has long provided a way to emit warnings from stylesheets, but it’s only recently added support to throw errors as well—and for good reason! Over the last few years, Sass has allowed authors to build complex systems to abstract difficult or repetitive patterns and concepts, such as grids. These systems must be able to communicate with authors, stopping the compilation process with a custom error message if anything ever goes wrong.

Both warnings and errors are emitted in the current output channel. When compiling Sass by hand or by using a tool through a command line interface (CLI) such as Grunt or Gulp, the output stream is the console. For tools that include a user interface, such as Codekit or Prepros, it’s likely that they catch and display warnings and errors as part of their interface. Online playgrounds such as CodePen and SassMeister manage to catch errors but not warnings, so don’t be alarmed if you’re unable to test them in there.


As has been stated, the ability to emit warnings in Sass is not new. It’s possible to display messages or the value of any SassScript expression to the standard output stream through the @warn directive.

A warning has no impact on the compilationprocess; it does not prevent compiling to pursue or change it in any way. Its only purpose is to display a message in the console.

There are a lot of reasons to use warnings in Sass. Here are a couple, but you’re likely to find your own:

informing the user of an assumption made about the code in order to avoid surprise and hard-to-track bugs
advising about a deprecated function or mixin as part of a library or framework

Sending a warning is dead simple to do: start with the @warn directive, then state whatever it is. Warnings are usually made to provide some information and context, so they often feature a sentence explaining the situation. That being said, you don’t have to use a string; you can warn with a number, a list, a map—whatever. Here, we print a string:

@warn ‘Uh-oh, something looks weird.’;

Using a regular CLI client, this warning will emit the following output:

WARNING: Uh-oh, something looks weird.
on line 1 of /Users/hgiraudel/jump-start-sass/warning.scss

Hey, that’s nice, isn’t it? Although this warning is far from helpful. It says that something looks weird but does not say what, why, or what can be done to stop it from looking weird. We’ll discuss how we can improve on warnings further on.

Let’s move on to a more serious example now that we know how to use he feature. Imagine we have a Sass custom function that attempts to convert a pixel value in em unit:

@function px-to-em($value, $base-font-size: 16px) {
@return ($value / $base-font-size) * 1em;

// Usage
.foo {
font-size: px-to-em(42px); // 2.625em

All good. Now, what happens when passing a unitless number—such as 42—to the function? Maybe you’ve guessed it, but as it’s not quite obvious I’ll give you the answer:

2.625em/px isn’t a valid CSS value.

This happens because you’re trying to perform a calculation between incompatible units (px and em). What we could do to circumvent this issue is assume the unitless value be expressed in pixels and convert it first:

@function px-to-em($value, $base-font-size: 16px) {
@if unitless($value) {
@warn ‘Assuming value `#{$value}` to be in pixels; attempting to convert it.’;
$value: $value * 1px;


@return ($value / $base-font-size) * 1em;

The function is expecting a value expressed in pixels. We can still make it work with a unitless value; however, we cannot be sure that this is the expected behavior. We can only assume that it’s good enough.

Because we’re assuming what is the correct behavior for our function, it’s important to let the developer know what we’re doing and why. Otherwise it could lead to bugs that are hard to track, which is not
what you should be aiming for.

Another practical example would be to warn against the usage of a deprecated function or mixin. You might have already heard of or used Bourbon, a lightweight mixin library for Sass. Bourbon is actively maintained, and sometimes requires removing helpers from the library. To avoid suddenly breaking a person’s ode, Bourbon warns about future deprecations way before it actually removes mixins:

@mixin inline-block {
display: inline-block;

@warn ‘The `inline-block` mixin is deprecated and will be removed in the next major version release.’;

Clever! People who still use the inline-block mixin from Bourbon are aware that the library will remove it completely in the next version, so they know to start updating their codebase to remove the mixin.

The Difference between @warn and @debug

You may or may not be familiar with the @debug directive, which prints the value of a SassScript expression to the standard output stream in the same fashion as @warn. You might be wondering why there are two features performing the same task, and what could possibly be the difference between the two.

Continue reading %How to Use Warnings and Errors in Sass Effectively%

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *