The Sass @error rule is written @error <expression>;. It prints the value (usually a string) along with a stack trace showing how the current mixin or function was called, then stops compiling and reports failure to your build tool.
Use it when writing mixins and functions that take arguments: if types or formats are wrong, notify the user and refuse to continue. Soft tips belong in @warn; value inspection belongs in @debug.
Official pattern.
Per the Sass docs: guard mixin keywords early (for example only left / right) with an interpolated message that names the bad value.
Hard fail on purpose.
If continuing would emit broken or incomplete CSS, prefer @error over silently shipping wrong styles.
Write actionable messages.
Say what was wrong, what was received, and what is allowed — not a vague "Invalid argument."
Syntax
Syntax
SCSS
@mixin reflexive-position($property, $value) {
@if $property != left and $property != right {
@error "Property #{$property} must be either left or right.";
}
$left-value: if($property == right, initial, $value);
$right-value: if($property == right, $value, initial);
left: $left-value;
right: $right-value;
[dir=rtl] & {
left: $right-value;
right: $left-value;
}
}
.sidebar {
@include reflexive-position(top, 12px);
}
Passing top prints an error and a stack that points at the include — no CSS is produced for that compile.
Passing top triggers @error and stops the compile.
SCSS
@mixin reflexive-position($property, $value) {
@if $property != left and $property != right {
@error "Property #{$property} must be either left or right.";
}
$left-value: if($property == right, initial, $value);
$right-value: if($property == right, $value, initial);
left: $left-value;
right: $right-value;
}
.sidebar {
@include reflexive-position(top, 12px);
}
Compiler error (no CSS produced)
Error: "Property top must be either left or right."
╷
3 │ @error "Property #{$property} must be either left or right.";
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
╵
invalid.scss 3:5 reflexive-position()
invalid.scss 14:3 root stylesheet
How It Works
The guard rejects top.
Sass prints the message and a stack trace.
Compilation aborts — no CSS ships.
Fix the include instead of debugging broken layout later.
Example 3 — Type Guard (Valid)
Assert a number, then use it in a calculation.
SCSS
@use "sass:meta";
@use "sass:math";
@function assert-number($value, $name: "value") {
@if meta.type-of($value) != number {
@error "#{$name} must be a number; got #{meta.type-of($value)} (#{$value}).";
}
@return $value;
}
.card {
opacity: math.div(assert-number(80, "$opacity"), 100);
}
Compiled CSS
.card {
opacity: 0.8;
}
How It Works
80 is a number, so the assert returns it.
math.div produces 0.8.
Reusable helper keeps type checks in one place.
Name the argument in the message for clearer call-site fixes.
Example 4 — Type Guard (Invalid)
A string fails the same assert with a detailed message.
SCSS
@use "sass:meta";
@function assert-number($value, $name: "value") {
@if meta.type-of($value) != number {
@error "#{$name} must be a number; got #{meta.type-of($value)} (#{$value}).";
}
@return $value;
}
.card {
opacity: assert-number("eighty", "$opacity");
}
Compiler error (no CSS produced)
Error: "$opacity must be a number; got string (eighty)."
╷
11 │ opacity: assert-number("eighty", "$opacity");
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
╵
type-fail.scss 11:12 root stylesheet
How It Works
Type is string, so the guard fires.
Message includes type and value for a fast fix.
Stack points at the call site in the root stylesheet.
No opacity CSS is emitted until the argument is fixed.
Example 5 — Unit & Range Checks
Accept unitless or % amounts only within 0–100.
SCSS
@use "sass:math";
@use "sass:meta";
@function clamp-percent($amount) {
@if meta.type-of($amount) != number {
@error "$amount must be a number.";
}
@if not math.is-unitless($amount) and math.unit($amount) != "%" {
@error "$amount must be unitless or %; got #{$amount}.";
}
@if $amount < 0 or $amount > 100 {
@error "$amount must be between 0 and 100; got #{$amount}.";
}
@return $amount;
}
.badge {
--tint: #{clamp-percent(40%)};
width: clamp-percent(50) * 1%;
}
Compiled CSS
.badge {
--tint: 40%;
width: 50%;
}
How It Works
Both calls pass type, unit, and range checks.
Unitless 50 is scaled to 50% in CSS.
Values like 120, -5%, or 10px would hit @error.
Layered guards keep each failure message specific.
Edge Cases & Pitfalls
Most @error issues are vague messages, wrong severity, or validating too late.
message
Include the bad value
Interpolate with #{$value} and name allowed options. Vague "Invalid." messages waste time.
severity
Do not hard-fail soft advice
Deprecations and tips belong in @warn. Reserve @error for usage that must not continue.
order
Validate before emitting CSS
Put guards at the top of mixins/functions so bad calls never partial-emit styles.
scope
Focus on public APIs
Over-guarding private helpers can make internals brittle. Guard what callers actually pass.
Toolchain
Sass Support
@error is a core Dart Sass at-rule. Stack-trace formatting varies slightly by implementation and build tool; stopping the compile is consistent.
Implementation
Status
Dart Sass
Supported (recommended)
LibSass / node-sass
Supported (deprecated toolchain)
Ruby Sass
Supported (end-of-life)
Browsers
N/A — no CSS ships after @error
Prefer Dart Sass for new projects. SCSS and indented syntax both support @error.
Remember
Key Takeaways
Hard fail:@error prints a message + stack and stops the build.
Guard APIs in mixins/functions before emitting styles.
Interpolate bad values and name what is allowed.
Soft tips? Use @warn. Inspecting? Use @debug.
One line:@error refuses bad API usage loudly so broken CSS never ships.
Compile
Compile Notes
@error never reaches the browser. Conceptual flow:
flow.txt
1. Call a mixin / function with arguments
2. Run validation guards (@if + checks)
3. If invalid → @error prints message + stack
4. Sass stops compiling and reports failure
5. Fix the call site, then recompile
Frequently Asked Questions
It prints the value of an expression (usually a string) plus a stack trace, then stops compiling the stylesheet and reports a failure to your build tool.
Use it in mixins and functions to enforce your API: wrong types, out-of-range values, unsupported keywords, or missing required configuration.
@error stops compilation. @warn prints a warning and continues. Use @warn for soft deprecations; use @error when continuing would produce broken CSS.
No. If @error runs, no finished CSS is produced for that compile. Browsers never see @error.
Yes. Interpolate with #{$name} so callers see the bad value, for example @error "Got #{$property}, expected left or right."
Implementations vary. Dart Sass typically shows the failing call site and how you reached the mixin or function. Exact formatting depends on your Sass version and build system.
