gohugoio/hugo · error

got unexpected EOF when executing %q. The user running hugo

Error message

got unexpected EOF when executing %q. The user running hugo must have read and execute permissions on this program. With execute permissions only, this error is thrown.

What it means

Hugo runs the Dart Sass compiler (`dart-sass`/`sass` embedded binary) as an external process via the godartsass transpiler, communicating over stdin/stdout. When executing a SCSS/Sass transform, if the child process dies immediately the protocol read returns 'unexpected EOF'. Hugo wraps that into this friendlier message because the most common cause is the binary being executable but not readable by the current user, so the OS starts it but the embedded snapshot cannot be loaded.

Source

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

}

func (c *Client) Close() error {
	if c.transpiler == nil {
		return nil
	}
	return c.transpiler.Close()
}

func (c *Client) toCSS(args godartsass.Args, src io.Reader) (godartsass.Result, error) {
	in := helpers.ReaderToString(src)

	args.Source = in

	res, err := c.transpiler.Execute(args)
	if err != nil {
		if err.Error() == "unexpected EOF" {
			//lint:ignore ST1005 end user message.
			return res, fmt.Errorf("got unexpected EOF when executing %q. The user running hugo must have read and execute permissions on this program. With execute permissions only, this error is thrown.", hugo.DartSassBinaryName)
		}
		return res, herrors.NewFileErrorFromFileInErr(err, hugofs.Os, herrors.OffsetMatcher)
	}

	return res, err
}

type Options struct {
	// Hugo, will by default, just replace the extension of the source
	// to .css, e.g. "scss/main.scss" becomes "scss/main.css". You can
	// control this by setting this, e.g. "styles/main.css" will create
	// a Resource with that as a base for RelPermalink etc.
	TargetPath string

	// Hugo automatically adds the entry directories (where the main.scss lives)
	// for project and themes to the list of include paths sent to LibSASS.
	// Any paths set in this setting will be appended. Note that these will be
	// treated as relative to the working dir, i.e. no include paths outside the

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Check permissions: `ls -l $(which sass)` (or dart-sass-embedded) and ensure the hugo user has both read and execute: `chmod a+rx <path-to-sass-binary>` (and the sibling `src/dart` files in the dart-sass distribution).
2. Verify the binary actually runs standalone as the same user: `sass --version`; reinstall dart-sass from the official release archive if it fails or the download was truncated.
3. Confirm the binary matches the host architecture (e.g. arm64 vs amd64 in Docker) and required libs are present.
4. In containers, install dart-sass in the Dockerfile with explicit `chmod -R a+rx` and run `hugo` as the same user, or switch `transpiler` to `libsass` as a workaround.

Example fix

# before (Dockerfile)
ADD dart-sass.tar.gz /opt/
ENV PATH=/opt/dart-sass:$PATH
# after
ADD dart-sass.tar.gz /opt/
RUN chmod -R a+rx /opt/dart-sass
ENV PATH=/opt/dart-sass:$PATH

// verify dart-sass binary is readable+executable before building
if fi, err := os.Stat(dartSassPath); err != nil {
    return fmt.Errorf("dart-sass not found: %w", err)
} else if fi.Mode()&0o500 != 0o500 {
    return fmt.Errorf("dart-sass at %s needs read+execute permissions, has %v", dartSassPath, fi.Mode())
}

if err := scssBuild(); err != nil && strings.Contains(err.Error(), "unexpected EOF") {
    log.Fatalf("check that the hugo user has BOTH read and execute permission on the dart-sass binary: %v", err)
}

When it happens

Trigger: Calling `css.Sass` / `resources.ToCSS` with `transpiler = dartsass` on a system where the `dart-sass-embedded`/`sass` binary on PATH has execute permission but not read permission for the hugo user, or where the binary is truncated/corrupted or killed at startup (e.g. wrong architecture, missing shared libs), causing godartsass Execute to fail with io.ErrUnexpectedEOF.

Common situations: CI/Docker images where dart-sass was installed as root with restrictive modes (e.g. chmod 111 or 700), extracting the dart-sass release archive without preserving permissions, running hugo as a different low-privilege user (www-data, CI runner) than the one that installed sass, snap-packaged sass with confinement issues, or an incomplete download of the dart-sass release.

Related errors

• no Dart Sass binary found in $PATH
• failed to save file %q:: %w
• failed to save file %q: %s
• failed to create workingDir: %w
• failed to open non-content file: %w

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