Sass @warn Rule

What You’ll Learn

Sass @warn prints a message and stack trace without stopping compilation. This page covers syntax, deprecation warnings, soft validation, how @warn differs from @error and @debug, and five compiled examples.

What Is @warn?

Official docs: when writing mixins and functions, you may want to discourage users from passing certain arguments or values. They may be passing legacy arguments that are now deprecated, or calling your API in a way that is not quite optimal.

The @warn rule is written @warn <expression>. It prints the value (usually a string) plus a stack trace showing how the current mixin or function was called. Unlike @error, it does not stop Sass entirely.

• Warnings appear in the compiler / terminal / build log—not in the CSS file.
• Compilation continues, so CSS is still produced.
• Ideal for deprecations, typos you still handle, and soft API tips.
• Message format and stack traces vary by Sass implementation.

📝 Syntax

@use "sass:list";

$known-prefixes: webkit, moz, ms, o;

@mixin prefix($property, $value, $prefixes) {
  @each $prefix in $prefixes {
    @if not list.index($known-prefixes, $prefix) {
      @warn "Unknown prefix #{$prefix}.";
    }

    -#{$prefix}-#{$property}: $value;
  }
  #{$property}: $value;
}

Warn inside the branch that detects the problem, then continue with a sensible fallback or the original behavior so existing stylesheets keep compiling.

📤 Messages & Stack Traces

Official docs: the exact format of the warning and stack trace varies from implementation to implementation. In Dart Sass it often looks like this:

WARNING: Unknown prefix wekbit.
    example.scss 6:7   prefix()
    example.scss 16:3  root stylesheet

⚖️ @warn vs @error vs @debug

Choose @warn when CSS can still be correct (or safely remapped). Choose @error when emitting CSS would be wrong or dangerous.

🛡️ Common @warn Patterns

• Unknown but tolerated values — typo’d vendor prefixes still emit.
• Deprecations — old size names remap to new ones with a warning.
• Soft type fallbacks — wrong type gets a default plus a warning (prefer @error for public APIs when possible).
• Missing map keys — fall back to a default theme token.
• Alias functions — fg() warns and forwards to foreground().

Examples Gallery

Each example still produces CSS. Open View Compiled CSS and View Compiler Warning to see both sides of @warn.

@use "sass:list";

$known-prefixes: webkit, moz, ms, o;

@mixin prefix($property, $value, $prefixes) {
  @each $prefix in $prefixes {
    @if not list.index($known-prefixes, $prefix) {
      @warn "Unknown prefix #{$prefix}.";
    }

    -#{$prefix}-#{$property}: $value;
  }
  #{$property}: $value;
}

.tilt {
  // Oops, we typo'd "webkit" as "wekbit"!
  @include prefix(transform, rotate(15deg), wekbit ms);
}

.tilt {
  -wekbit-transform: rotate(15deg);
  -ms-transform: rotate(15deg);
  transform: rotate(15deg);
}

WARNING: Unknown prefix wekbit.
    warn-prefix.scss 8:7   prefix()
    warn-prefix.scss 17:3  root stylesheet

@mixin button($size: md) {
  @if $size == xl {
    @warn "The xl size is deprecated. Use lg instead.";
    $size: lg;
  }

  @if $size == sm {
    padding: 0.25rem 0.5rem;
    font-size: 0.875rem;
  } @else if $size == md {
    padding: 0.5rem 1rem;
    font-size: 1rem;
  } @else {
    padding: 0.75rem 1.25rem;
    font-size: 1.125rem;
  }
}

.cta {
  @include button(xl);
}

.cta {
  padding: 0.75rem 1.25rem;
  font-size: 1.125rem;
}

WARNING: The xl size is deprecated. Use lg instead.
    warn-deprecate.scss 3:5   button()
    warn-deprecate.scss 20:3  root stylesheet

@use "sass:meta";
@use "sass:math";

@function scale-opacity($value) {
  @if meta.type-of($value) != number {
    @warn "scale-opacity() expected a number; got #{meta.type-of($value)}. Using 1.";
    @return 1;
  }
  @return math.div($value, 100);
}

.card {
  opacity: scale-opacity(80);
}

.broken {
  opacity: scale-opacity("eighty");
}

.card {
  opacity: 0.8;
}

.broken {
  opacity: 1;
}

WARNING: scale-opacity() expected a number; got string. Using 1.
    warn-fallback.scss 6:5    scale-opacity()
    warn-fallback.scss 17:12  root stylesheet

@use "sass:map";

@mixin theme-color($name) {
  $palette: (
    primary: #036,
    accent: #c45,
  );

  @if not map.has-key($palette, $name) {
    @warn "Unknown theme color `#{$name}`. Falling back to primary.";
    $name: primary;
  }

  color: map.get($palette, $name);
}

.text {
  @include theme-color(accent);
}

.miss {
  @include theme-color(neon);
}

.text {
  color: #c45;
}

.miss {
  color: #036;
}

WARNING: Unknown theme color `neon`. Falling back to primary.
    warn-theme.scss 10:5  theme-color()
    warn-theme.scss 22:3  root stylesheet

@function fg($args...) {
  @warn "The fg() function is deprecated. Call foreground() instead.";
  @return foreground($args...);
}

@function foreground($color) {
  @return $color;
}

.title {
  color: fg(#222);
}

.title {
  color: #222;
}

WARNING: The fg() function is deprecated. Call foreground() instead.
    warn-alias.scss 2:3    fg()
    warn-alias.scss 11:10  root stylesheet

🚀 Real-World Use Cases

• API migrations — deprecate old argument names with a remap.
• Design-system releases — warn before removing a token in the next major.
• Typo detection — unknown prefixes or theme keys that still compile.
• Alias shims — keep fg() while promoting foreground().
• CI visibility — surface warnings in build logs without failing (unless you treat warnings as errors).

⚠️ Common Pitfalls

• Using @warn for fatal mistakes — if CSS would be wrong, use @error.
• Vague messages — always say what to use instead.
• Warning spam — avoid warning on every loop iteration when one summary is enough.
• Assuming users see warnings — some CI setups hide or ignore them.
• Forever deprecations — plan a timeline to remove the old path.

💡 Best Practices