gohugoio/hugo · error

unsupported transpiler

Error message

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

What it means

`css.Sass` (css.go:159-169) reads an optional `transpiler` key from the options map (case-insensitive via `hmaps.LookupEqualFold`). Valid values are the string constants `sass.TranspilerLibSass` (`"libsass"`) and `sass.TranspilerDart` (`"dartsass"`). Any other value reaches the `default` arm and returns this error quoting the bad value and the two valid choices. Note `libsass` is deprecated (v0.153.0+) in favor of `dartsass`.

Solutions

1. Set `transpiler` to `"dartsass"` (recommended) or `"libsass"` (legacy).
2. Remove the `transpiler` key to accept the default (currently libsass, migrating to dartsass).
3. Ensure the dart-sass binary is installed when using `dartsass`.

Example fix

// before
{{ $css := $main | css.Sass (dict "transpiler" "sass") }}
// after
{{ $css := $main | css.Sass (dict "transpiler" "dartsass") }}

{{/* Valid transpilers: dartsass (recommended), libsass (deprecated) */}}
{{ $main | css.Sass (dict "transpiler" "dartsass") }}
{{ $main | css.Sass }} {{/* default */}}

When it happens

Trigger: `{{ $css := $main | css.Sass (dict "transpiler" "sass") }}`, `{{ ... | css.Sass (dict "transpiler" "node") }}`, or a typo.

Common situations: Using `"sass"` or `"ruby"`/`"node-sass"`; uppercase `"DartSass"`; migrating to dartsass but misspelling it.

Related errors

• crypto.Hash: is not a supported hash algorithm
• hmac: is not a supported hash function
• is not a supported encoding method
• can't evaluate a nil pointer of type
• crypto.Hash: expected 1 or 2 arguments, got

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/72dd6f75aa6a7240. Report an issue: GitHub.

Appendix: 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 52c9bd7908)