gohugoio/hugo · error

no Dart Sass binary found in $PATH

Error message

no Dart Sass binary found in $PATH

What it means

Raised in the Dart Sass client constructor when Hugo is configured to use the `dartsass` transpiler but no `sass` (dart-sass-embedded) executable was found in $PATH at startup (hugo.DartSassBinaryName is empty). Hugo shells out to the Dart Sass binary rather than bundling it, so it must be installed separately.

Source

Thrown at resources/resource_transformers/tocss/dartsass/client.go:52

	"github.com/spf13/afero"

	"github.com/mitchellh/mapstructure"
)

// used as part of the cache key.
const transformationName = "tocss-dart"

// See https://github.com/sass/dart-sass-embedded/issues/24
// Note: This prefix must be all lower case.
const dartSassStdinPrefix = "hugostdin:"

func New(fs *filesystems.SourceFilesystem, rs *resources.Spec) (*Client, error) {
	if !Supports() {
		return &Client{}, nil
	}

	if hugo.DartSassBinaryName == "" {
		return nil, fmt.Errorf("no Dart Sass binary found in $PATH")
	}

	if !hugo.IsDartSassGeV2() {
		return nil, fmt.Errorf("unsupported Dart Sass version detected, please upgrade to Dart Sass 1.63.0 or later, see https://gohugo.io/functions/css/sass/#dart-sass")
	}

	if err := rs.ExecHelper.Sec().CheckAllowedExec(hugo.DartSassBinaryName); err != nil {
		return nil, err
	}

	var (
		transpiler *godartsass.Transpiler
		err        error
		infol      = rs.Logger.InfoCommand("Dart Sass")
		warnl      = rs.Logger.WarnCommand("Dart Sass")
	)

	transpiler, err = godartsass.Start(godartsass.Options{

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install Dart Sass and ensure `sass --version` works in the same shell: `brew install sass/sass/sass`, `choco install sass`, `npm i -g sass`, or download from https://github.com/sass/dart-sass/releases
2. In CI, add an install step (e.g. GitHub Actions: install dart-sass before `hugo`)
3. If PATH differs for the build process (systemd, snap), add the sass binary directory to that PATH
4. Alternatively switch the pipeline to `transpiler = "libsass"` if the built-in transpiler suffices

Example fix

# before (CI)
- run: hugo --minify
# after
- run: |
    curl -sL https://github.com/sass/dart-sass/releases/download/1.77.8/dart-sass-1.77.8-linux-x64.tar.gz | tar xz
    export PATH="$PWD/dart-sass:$PATH"
    hugo --minify

# before build
command -v sass || { echo 'install dart-sass'; exit 1; }

{{ if hugo.IsExtended }}{{ with try (. | css.Sass (dict "transpiler" "dartsass")) }}{{ with .Err }}{{ warnf "%s" . }}{{ end }}{{ end }}{{ end }}

When it happens

Trigger: A template pipeline using `css.Sass` / `toCSS` with `transpiler = "dartsass"` (or a theme requiring it) on a machine where the `sass` binary is not installed or not on the PATH visible to Hugo.

Common situations: Fresh dev machines, CI runners (GitHub Actions, Netlify, Vercel) without a dart-sass install step, Snap-packaged Hugo which has a confined PATH, or Docker images containing only the hugo binary.

Related errors

• unsupported Dart Sass version detected, please upgrade to Da
• got unexpected EOF when executing %q. The user running hugo
• pandoc not found in $PATH, cannot render %q
• rst2html / rst2html.py not found in $PATH, cannot render %q
• ErrFeatureNotAvailable

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