@debug, @warn and @error

Sass code runs on your computer, not in the browser, so there is no console to look into. Instead Sass has three rules that print messages to the terminal where the compiler runs: @debug shows a value, @warn warns, and @error stops the build.

@debug — look at a value

@debug prints any expression together with the file name and line number. It is useful when a calculation gives an unexpected result:

// styles/main.scss
@use "sass:math";
 
$base: 16px;
$size: math.div(24px, $base) * 1rem;
 
@debug $size;

When you run npx sass styles/main.scss css/main.css, the terminal shows:

styles/main.scss:7 DEBUG: 1.5rem

@debug does not get into the CSS. Remove it when the problem is found.

@warn — warn but continue

@warn prints a warning with the call stack — which mixin was called from which line — and compiling continues. Use it for arguments that work but are probably a mistake:

// styles/abstracts/_mixins.scss
@mixin columns($count) {
  @if $count > 6 {
    @warn "#{$count} columns are hard to read on small screens.";
  }
  grid-template-columns: repeat($count, 1fr);
}

// styles/main.scss
@use "abstracts/mixins";
 
.gallery {
  @include mixins.columns(8);
}

The CSS is created, and the terminal shows:

WARNING: 8 columns are hard to read on small screens.
    styles/abstracts/_mixins.scss 4:5  columns()
    styles/main.scss 5:3               root stylesheet

@error — stop the build

@error stops compiling and shows the message; the styles are not built. This is the right reaction to a value that cannot work, such as an unknown key of a map:

// styles/abstracts/_functions.scss
@use "sass:map";
 
$colors: ("primary": #2563eb, "danger": #dc2626);
 
@function color($name) {
  @if not map.has-key($colors, $name) {
    @error "Unknown colour '#{$name}'. Available: #{map.keys($colors)}.";
  }
  @return map.get($colors, $name);
}

// styles/main.scss
@use "abstracts/functions";
 
.alert {
  color: functions.color("warning");
}

The terminal shows the message and the place of the call:

Error: "Unknown colour 'warning'. Available: primary, danger."
  ╷
5 │   color: functions.color("warning");
  │          ^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  styles/main.scss 5:10  root stylesheet

Without the check the typo would silently give an empty value. With it, the build fails immediately and says what is available.

Which one to use

In a Vite project the same messages appear in the terminal where npm run dev runs.

Common mistake

Do not leave @debug lines in the code. Each one prints a line on every compile, and in watch mode the terminal fills up with noise that hides real warnings. Search the project for @debug before committing.