Sass Error Handling — @error, @warn, and @debug Directives

In this tutorial, you will learn about Sass Error Handling. We cover key concepts, practical examples, and best practices to help you master this topic.

Sass provides three directives for handling errors and debugging: @error stops compilation with a message, @warn prints a warning, and @debug prints values during development.

What You'll Learn

You will learn how to use @error for input validation, @warn for deprecation notices, @debug for troubleshooting, and how to handle common edge cases in mixins and functions.

Why It Matters

Proper error handling prevents broken CSS from reaching production. DodaTech's build pipeline uses @error directives in shared mixins to catch invalid color values and spacing units before they cause layout bugs.

Real-World Use

Doda Browser's theme system uses @error to reject invalid theme color values and @warn when deprecated variable names are used, guiding developers toward the correct API.

flowchart LR
    A[Control Directives] --> B[Error Handling]
    B --> C[@error]
    B --> D[@warn]
    B --> E[@debug]
    B --> F[Validation]
    B --> G[Production Safety]
    style B fill:#c69,stroke:#c69,color:#fff
    style C fill:#ef4444,stroke:#dc2626,color:#fff
    style D fill:#f59e0b,stroke:#d97706,color:#fff

Using @error for Validation

@mixin font-size($size) {
  @if $size < 0.5rem or $size > 5rem {
    @error "Font size #{$size} is out of range. Must be between 0.5rem and 5rem.";
  }
  font-size: $size;
  line-height: 1.2;
}

h1 {
  @include font-size(6rem);
}

Expected output: Compilation fails with: "Error: Font size 6rem is out of range. Must be between 0.5rem and 5rem."

Using @warn for Deprecation

$primary-color: #7c3aed !default;

// @mixin button-color($bg) - deprecated, use theme-color() instead
@mixin button-color($bg) {
  @warn "button-color() is deprecated. Use theme-color() instead.";
  background: $bg;
  color: if(lightness($bg) > 50, #000, #fff);
}

.button {
  @include button-color($primary-color);
}

Expected output: A warning message during compilation: "WARNING: button-color() is deprecated. Use theme-color() instead." The CSS still compiles successfully.

Using @debug for Troubleshooting

$breakpoints: (
  sm: 640px,
  md: 768px,
  lg: 1024px,
  xl: 1280px
);

@function get-breakpoint($name) {
  @debug "Looking up breakpoint: #{$name}";
  @debug "Available keys: #{map-keys($breakpoints)}";
  @return map-get($breakpoints, $name);
}

.container {
  max-width: get-breakpoint(1320);
}

Expected output: Debug messages print to the console showing the lookup value and available keys. The function returns null since 1320 is not a valid key.

Validating Multiple Parameters

@mixin spacing($property, $value) {
  $valid-properties: (margin, padding, gap);
  @if not index($valid-properties, $property) {
    @error "Invalid property '#{$property}'. Valid: #{$valid-properties}.";
  }
  @if type-of($value) != number {
    @error "Value must be a number. Got #{type-of($value)}: #{$value}.";
  }
  $valid-units: (px, rem, em, percent);
  @if not index($valid-units, unit($value)) {
    @warn "Unusual unit '#{unit($value)}'. Expected px, rem, em, or percent.";
  }
  #{$property}: $value;
}

.card {
  @include spacing(padding, 1rem);
}

Expected output: No errors. The mixin validates property name, value type, and unit. Compiles to .card { padding: 1rem; }.

Combining Conditions for Robust Validation

@function contrast-color($bg) {
  @if type-of($bg) != color {
    @error "contrast-color() requires a color value. Got #{type-of($bg)}: #{$bg}.";
  }
  @if lightness($bg) < 0 or lightness($bg) > 100 {
    @error "Lightness value out of range. Got #{lightness($bg)} percent.";
  }
  $threshold: 50;
  @return if(lightness($bg) > $threshold, #000, #fff);
}

.dark-bg {
  color: contrast-color(#1e1b4b);
}

.light-bg {
  color: contrast-color(#f5f3ff);
}

Compiles to:

.dark-bg { color: #fff; }
.light-bg { color: #000; }

Expected output: Dark background gets white text, light background gets black text, based on the 50 percent lightness threshold.

Common Mistakes

1. Using @error When @warn Is Appropriate

@error stops compilation entirely. Use @warn for deprecations and minor issues, not for show-stopping validation failures.

2. Forgetting String Interpolation in Messages

Variables inside error messages need #{} interpolation: @error "Invalid value: #{$value}." not @error "Invalid value: $value.".

3. Not Checking type-of() Before Operations

Calling color functions on non-color values or math functions on strings causes hard-to-debug Sass errors.

4. Using @debug in Production Code

@debug messages clutter output. Remove @debug calls from production mixins, or gate them behind a $debug variable.

5. Ignoring @warn Messages

Warnings compile successfully but indicate potential issues. Set your CI to treat warnings as errors in production builds.

Practice Questions

1. What happens when @error is encountered? Compilation stops immediately and the error message is displayed to the developer.

2. How does @warn differ from @error? @warn prints a warning but compilation continues. @error halts compilation.

3. What syntax is needed to include variable values in messages? String interpolation: #{$variable} inside double-quoted strings.

4. Why should @debug be removed from production code? It prints extraneous messages that slow compilation and clutter output.

5. How do you check a value's type in Sass? Use type-of($value) which returns a string like "color", "number", "string", or "list".

Challenge

Write a @mixin box-shadow that validates: the value count (must be 4 or 5 values), each value type (must be numbers), and the color value (must be a color). Use @error for critical failures and @warn for unusual units like cm or in.

FAQ

Mini Project

Create a @mixin responsive-font that accepts a min and max font size. Validate both arguments are positive numbers with rem or px units. @error if min exceeds max, @warn if units mismatch. Test with valid and invalid calls.

What's Next

With error handling mastered, explore Interpolation for dynamic property and selector names. Then apply everything in the Sass Project capstone.