Sass @error Rule

What You’ll Learn

Sass @error stops compilation and prints a clear message (plus a stack trace) when something is wrong. This page covers syntax, validating mixin/function arguments, type and range checks, how errors differ from @warn / @debug, and five practical examples.

What Is @error?

Official docs: when mixins and functions take arguments, you usually want to ensure those arguments have the types and formats your API expects. If they are not, the user needs to be notified and your mixin/function needs to stop running.

Sass makes this easy with @error, written @error <expression>. It prints the value of the expression (usually a string) along with a stack trace, then stops compiling and tells your build system that an error occurred.

• Best used inside mixins and functions.
• No CSS is emitted for a failed compile once @error runs.
• Message formatting and stack traces vary by Sass implementation and build tool.
• Interpolate values with #{$var} so the bad input shows up in the message.

📝 Syntax

@mixin reflexive-position($property, $value) {
  @if $property != left and $property != right {
    @error "Property #{$property} must be either left or right.";
  }

  // … emit styles only when validation passes
}

Put the check near the top of the mixin or function. Fail fast before you compute or emit anything based on bad input.

📤 Messages & Stack Traces

Official docs: the exact format of the error and stack trace varies by implementation and can also depend on your build system. In Dart Sass from the command line, you typically see the message, a caret pointing at the failing line, and frames for the mixin/function and the root stylesheet.

Error: "Property top must be either left or right."
  ╷
3 │     @error "Property #{$property} must be either left or right.";
  │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  example.scss 3:5   reflexive-position()
  example.scss 19:3  root stylesheet

⚖️ @error vs @warn vs @debug

Use @error when continuing would silently produce wrong or incomplete CSS. Use @warn when you want to nudge callers without breaking the build.

🛡️ Common Validation Patterns

• Allowed keywords — only left / right, or a fixed map of modes.
• Types — meta.type-of($value) == number (or color, list, …).
• Units — math.unit($x) or math.is-unitless($x).
• Ranges — reject negatives or values outside 0–100.
• Required config — fail if a map key or module variable is missing.

@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;
}

Examples Gallery

Valid calls show compiled CSS. Invalid calls show the compiler error (no CSS is produced). Open the output buttons to compare both paths.

@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(left, 12px);
}

.sidebar {
  left: 12px;
  right: initial;
}
[dir=rtl] .sidebar {
  left: initial;
  right: 12px;
}

@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);
  // Error: Property top must be either left or right.
}

Error: "Property top must be either left or right."
  ╷
3 │     @error "Property #{$property} must be either left or right.";
  │     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  error-invalid.scss 3:5   reflexive-position()
  error-invalid.scss 14:3  root stylesheet

@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);
}

.card {
  opacity: 0.8;
}

@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");
}

Error: "$opacity must be a number; got string (eighty)."
  ╷
11 │   opacity: assert-number("eighty", "$opacity");
   │            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  error-type-fail.scss 11:12  root stylesheet

@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%;
}

.badge {
  --tint: 40%;
  width: 50%;
}

🚀 Real-World Use Cases

• Design-system APIs — reject unknown button sizes or themes.
• Shared helpers — assert numbers before math.div.
• Config modules — fail if required map keys are missing after @use … with.
• Breaking changes — hard-fail removed options instead of ignoring them.
• Teaching / code reviews — make incorrect includes fail loudly in CI.

⚠️ Common Pitfalls

• Vague messages — always include the bad value and allowed options.
• Using @error for soft advice — prefer @warn for deprecations.
• Validating too late — check arguments before emitting styles.
• Forgetting interpolation — @error $value may print awkwardly; prefer a clear string with #{$value}.
• Over-guarding private helpers — focus errors on public API surfaces.

💡 Best Practices