gohugoio/hugo · error

unsupported transpiler %q; valid values are %q or %q

Error message

unsupported transpiler %q; valid values are %q or %q

What it means

css.Sass accepts a transpiler option that must be either "libsass" or "dartsass". Any other value is rejected. Note libsass is the (deprecated as of v0.153.0) default; dartsass is the recommended value going forward and requires the Dart Sass binary to be installed.

Source

Thrown at tpl/css/css.go:168

	r, targetPath, ok = resourcehelpers.ResolveIfFirstArgIsString(args)

	if !ok {
		r, m, err = resourcehelpers.ResolveArgs(args)
		if err != nil {
			return nil, err
		}
	}

	if m != nil {
		if t, _, found := hmaps.LookupEqualFold(m, "transpiler"); found {
			switch t {
			case sass.TranspilerDart:
				transpiler = cast.ToString(t)
			case sass.TranspilerLibSass:
				hugo.Deprecate("css.Sass: libsass", "Use dartsass instead. See https://gohugo.io/functions/css/sass/#dart-sass", "v0.153.0")
				transpiler = cast.ToString(t)
			default:
				return nil, fmt.Errorf("unsupported transpiler %q; valid values are %q or %q", t, sass.TranspilerLibSass, sass.TranspilerDart)
			}
		}
	}

	if transpiler == sass.TranspilerLibSass {
		var options scss.Options
		if targetPath != "" {
			options.TargetPath = paths.ToSlashTrimLeading(targetPath)
		} else if m != nil {
			options, err = scss.DecodeOptions(m)
			if err != nil {
				return nil, err
			}
		}

		return ns.scssClientLibSass.ToCSS(r, options)
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Set the option to exactly "dartsass" (or "libsass"): {{ $opts := dict "transpiler" "dartsass" }}.
2. Install Dart Sass and ensure the 'sass' binary is on PATH when switching to dartsass.
3. If the value comes from site config/params, verify the param actually contains one of the two accepted strings.

Example fix

{{/* before */}}
{{ $css := $scss | css.Sass (dict "transpiler" "dart-sass") }}

{{/* after */}}
{{ $css := $scss | css.Sass (dict "transpiler" "dartsass") }}

{{ $t := .Site.Params.transpiler | default "libsass" }}
{{ if not (in (slice "libsass" "dartsass") $t) }}
  {{ errorf "invalid transpiler %q; use libsass or dartsass" $t }}
{{ end }}
{{ $opts := dict "transpiler" $t }}

When it happens

Trigger: Passing (dict "transpiler" X) to css.Sass / toCSS where X is not exactly libsass or dartsass — e.g. "dart-sass", "dart", "sass", a typo, or a non-string that stringifies unexpectedly.

Common situations: Users following the libsass-deprecation notice write "dart-sass" or "dart sass" (the binary's name) instead of the option value "dartsass"; config values interpolated from site params can also carry wrong casing-insensitive-but-wrong strings.

Related errors

• failed to detect target data serialization format
• targetPath cannot be empty
• must not provide more arguments than resource object and opt
• postcss config %q not found
• failed to resolve CSS @import "%s"; %s

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/72dd6f75aa6a7240.json. Report an issue: GitHub ↗.