Sass @debug Rule

What You’ll Learn

Sass @debug prints the value of a variable or expression while you develop—along with the filename and line number. This page covers syntax, inspecting any Sass type, how @debug differs from @warn and @error, and five compiled examples.

What Is @debug?

Official docs: sometimes it is useful to see the value of a variable or expression while you are developing your stylesheet. That is what the @debug rule is for: written @debug <expression>, it prints the value of that expression, along with the filename and line number.

• Messages appear in the compiler / terminal / build log—not in the CSS file.
• Compilation continues; CSS is still produced.
• You can pass any Sass value, not just a string.
• Printed representation matches meta.inspect().
• Exact message format varies by Sass implementation.

📝 Syntax

@mixin inset-divider-offset($offset, $padding) {
  $divider-offset: (2 * $padding) + $offset;
  @debug "divider offset: #{$divider-offset}";

  margin-left: $divider-offset;
  width: calc(100% - #{$divider-offset});
}

Label the printed value with a short string so logs stay readable when you have several @debug lines.

📤 Debug Messages

Official docs: the exact format varies by implementation. In Dart Sass it often looks like:

test.scss:3 Debug: divider offset: 132px

⚖️ @debug vs @warn vs @error

Use @debug for yourself while building. Use @warn / @error when talking to other developers through your library API.

🛡️ Common @debug Patterns

• Intermediate math — print a computed length before it hits CSS.
• Maps & lists — inspect tokens and list.nth results.
• Inside functions — log inputs and the returned value.
• Loops — print each breakpoint or theme key as you iterate.
• Type checks — @debug meta.type-of($x) when values look wrong.

Examples Gallery

Each example still produces CSS. Open View Compiled CSS and View Debug Output to see both sides of @debug.

@mixin inset-divider-offset($offset, $padding) {
  $divider-offset: (2 * $padding) + $offset;
  @debug "divider offset: #{$divider-offset}";

  margin-left: $divider-offset;
  width: calc(100% - #{$divider-offset});
}

.panel {
  @include inset-divider-offset(12px, 60px);
}

.panel {
  margin-left: 132px;
  width: calc(100% - 132px);
}

debug-basic.scss:3 DEBUG: divider offset: 132px

@use "sass:map";
@use "sass:list";
@use "sass:meta";

$theme: (
  primary: #036,
  radius: 8px,
);

@debug $theme;
@debug map.get($theme, primary);
@debug list.nth(10px 20px 30px, 2);
@debug meta.type-of(#036);

.box {
  color: map.get($theme, primary);
  border-radius: map.get($theme, radius);
  padding: list.nth(10px 20px 30px, 2);
}

.box {
  color: #036;
  border-radius: 8px;
  padding: 20px;
}

debug-values.scss:10 DEBUG: (primary: #036, radius: 8px)
debug-values.scss:11 DEBUG: #036
debug-values.scss:12 DEBUG: 20px
debug-values.scss:13 DEBUG: color

@use "sass:math";

@function rem($px, $base: 16px) {
  $result: math.div($px, $base) * 1rem;
  @debug "rem(#{$px}, #{$base}) => #{$result}";
  @return $result;
}

.title {
  font-size: rem(24px);
  padding: rem(8px, 16px);
}

.title {
  font-size: 1.5rem;
  padding: 0.5rem;
}

debug-function.scss:6 DEBUG: rem(24px, 16px) => 1.5rem
debug-function.scss:6 DEBUG: rem(8px, 16px) => 0.5rem

$breakpoints: (
  sm: 480px,
  md: 768px,
  lg: 1024px,
);

@each $name, $width in $breakpoints {
  @debug "breakpoint #{$name} = #{$width}";

  @media (min-width: $width) {
    .container-#{$name} {
      max-width: $width;
    }
  }
}

@media (min-width: 480px) {
  .container-sm {
    max-width: 480px;
  }
}
@media (min-width: 768px) {
  .container-md {
    max-width: 768px;
  }
}
@media (min-width: 1024px) {
  .container-lg {
    max-width: 1024px;
  }
}

debug-loop.scss:8 DEBUG: breakpoint sm = 480px
debug-loop.scss:8 DEBUG: breakpoint md = 768px
debug-loop.scss:8 DEBUG: breakpoint lg = 1024px

@use "sass:color";
@use "sass:meta";

$brand: #036;

@debug $brand;
@debug color.scale($brand, $lightness: 40%);
@debug meta.inspect((ok: true, count: 3));
@debug null;
@debug "plain string";

.swatch {
  background: $brand;
  color: color.scale($brand, $lightness: 40%);
}

.swatch {
  background: #036;
  color: #0a85ff;
}

debug-types.scss:6 DEBUG: #036
debug-types.scss:7 DEBUG: #0a85ff
debug-types.scss:8 DEBUG: (ok: true, count: 3)
debug-types.scss:9 DEBUG: null
debug-types.scss:10 DEBUG: plain string

🚀 Real-World Use Cases

• Spacing math — confirm offsets before calc().
• Design tokens — inspect maps while building a theme.
• Helper functions — trace rem(), clamp, or color scales.
• Generated CSS — verify loop keys and media widths.
• Type confusion — print meta.type-of when a value misbehaves.

⚠️ Common Pitfalls

• Leaving @debug in production — noisy logs; remove when done.
• Using @debug as an API warning — prefer @warn for callers.
• Expecting CSS output — debug never appears in the stylesheet.
• Spam in loops — large maps can flood the terminal.
• Confusing with @error — @debug never fails the build.

💡 Best Practices