Hugo "TOCSS ... requires version that is extended" in CI

By Daniel Zoghalchali·Latchkey

The toCSS (Sass/SCSS) pipeline is only in Hugo Extended. When CI installed the standard Hugo binary, any SCSS transform fails with a message that the feature needs the extended version.

What this error means

hugo fails with "TOCSS: failed to transform ...: this feature is not available in your current Hugo version, install Hugo Extended" while processing a .scss asset.

Error: error building site: TOCSS: failed to transform "main.scss" (text/x-scss):
this feature is not available in your current Hugo version, install Hugo Extended to use it

Common causes

The standard Hugo binary is installed

Standard Hugo lacks the embedded Sass transpiler, so resources.ToCSS / css.Sass cannot run.

The setup step did not request extended

The Hugo install action or download fetched the non-extended build, so the SCSS pipeline is unavailable.

How to fix it

Install Hugo Extended in CI

1. Set the Hugo setup action to use the extended build.
2. Pin a Hugo version to keep builds reproducible.
3. Rebuild; SCSS now transpiles.

- uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: '0.128.0'
    extended: true

Verify the binary is extended

Confirm the installed binary reports extended before building.

hugo version   # should include "+extended"

How to prevent it

• Always install Hugo Extended when the site uses SCSS.
• Pin the Hugo version in CI.
• Check hugo version shows +extended.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation