{"id":"724d2c54318b23df","repo":"gohugoio/hugo","slug":"got-unexpected-eof-when-executing-q-the-user-run","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/resource_transformers/tocss/dartsass/client.go","lineNumber":124,"sourceCode":"}\n\nfunc (c *Client) Close() error {\n\tif c.transpiler == nil {\n\t\treturn nil\n\t}\n\treturn c.transpiler.Close()\n}\n\nfunc (c *Client) toCSS(args godartsass.Args, src io.Reader) (godartsass.Result, error) {\n\tin := helpers.ReaderToString(src)\n\n\targs.Source = in\n\n\tres, err := c.transpiler.Execute(args)\n\tif err != nil {\n\t\tif err.Error() == \"unexpected EOF\" {\n\t\t\t//lint:ignore ST1005 end user message.\n\t\t\treturn 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)\n\t\t}\n\t\treturn res, herrors.NewFileErrorFromFileInErr(err, hugofs.Os, herrors.OffsetMatcher)\n\t}\n\n\treturn res, err\n}\n\ntype Options struct {\n\t// Hugo, will by default, just replace the extension of the source\n\t// to .css, e.g. \"scss/main.scss\" becomes \"scss/main.css\". You can\n\t// control this by setting this, e.g. \"styles/main.css\" will create\n\t// a Resource with that as a base for RelPermalink etc.\n\tTargetPath string\n\n\t// Hugo automatically adds the entry directories (where the main.scss lives)\n\t// for project and themes to the list of include paths sent to LibSASS.\n\t// Any paths set in this setting will be appended. Note that these will be\n\t// treated as relative to the working dir, i.e. no include paths outside the","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/resource_transformers/tocss/dartsass/client.go#L106-L142","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","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.","Confirm the binary matches the host architecture (e.g. arm64 vs amd64 in Docker) and required libs are present.","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."],"exampleFix":"# before (Dockerfile)\nADD dart-sass.tar.gz /opt/\nENV PATH=/opt/dart-sass:$PATH\n# after\nADD dart-sass.tar.gz /opt/\nRUN chmod -R a+rx /opt/dart-sass\nENV PATH=/opt/dart-sass:$PATH","handlingStrategy":"validation","validationCode":"// verify dart-sass binary is readable+executable before building\nif fi, err := os.Stat(dartSassPath); err != nil {\n    return fmt.Errorf(\"dart-sass not found: %w\", err)\n} else if fi.Mode()&0o500 != 0o500 {\n    return fmt.Errorf(\"dart-sass at %s needs read+execute permissions, has %v\", dartSassPath, fi.Mode())\n}","typeGuard":null,"tryCatchPattern":"if err := scssBuild(); err != nil && strings.Contains(err.Error(), \"unexpected EOF\") {\n    log.Fatalf(\"check that the hugo user has BOTH read and execute permission on the dart-sass binary: %v\", err)\n}","preventionTips":["Install dart-sass with chmod 755, not 111 — execute-only permission triggers this exact EOF","In Docker/CI images, verify the sass binary permissions as the runtime (non-root) user, not as root","Run `sass --version` as the same user that runs hugo before the build","Pin the dart-sass version in CI so upgrades can't silently change install permissions"],"tags":["hugo","dart-sass","permissions","external-binary","scss"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}