gohugoio/hugo · error

%s: failed to transform %q (%s) <errMsg>: %w

Error message

%s: failed to transform %q (%s) <errMsg>: %w

What it means

Wrapper produced by Spec.Transform's newErr when a transformation returns a FeatureNotAvailableError. It formats '<NAME>: failed to transform "<path>" (<mediatype>)' and appends a transformation-specific hint (install PostCSS/TailwindCSS/Dart Sass/Babel, or use Hugo extended for libsass) before wrapping the cause. This is the canonical 'feature/tool not installed' error for the asset pipeline.

Source

Thrown at resources/transform.go:596

			if herrors.IsFeatureNotAvailableError(err) {
				var errMsg string
				switch strings.ToLower(tr.Key().Name) {
				case "postcss":
					// This transformation is not available in this
					// Most likely because PostCSS is not installed.
					errMsg = ". You need to install PostCSS. See https://gohugo.io/functions/css/postcss/"
				case "tailwindcss":
					errMsg = ". You need to install TailwindCSS CLI. See https://gohugo.io/functions/css/tailwindcss/"
				case "tocss":
					errMsg = ". Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'."
				case "tocss-dart":
					errMsg = ". You need to install Dart Sass, see https://gohugo.io//functions/css/sass/#dart-sass"
				case "babel":
					errMsg = ". You need to install Babel, see https://gohugo.io/functions/js/babel/"

				}

				return fmt.Errorf(msg+errMsg+": %w", err)
			}

			return fmt.Errorf(msg+": %w", err)
		}

		bcfg := r.spec.BuildConfig()
		var tryFileCache bool
		if mayBeCachedOnDisk && bcfg.UseResourceCache(nil) {
			tryFileCache = true
		} else {
			err = tr.Transform(tctx)
			if err != nil && err != herrors.ErrFeatureNotAvailable {
				return nil, newErr(err)
			}

			if mayBeCachedOnDisk {
				tryFileCache = bcfg.UseResourceCache(err)
			}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Install the named tool per the message's gohugo.io link (e.g. npm install postcss-cli tailwindcss @babel/cli, or Dart Sass, or switch to Hugo extended for libsass).
2. Run `hugo --gc` or `npm ci` to ensure deps are present before building.
3. If you intentionally pre-build assets, enable disk cache fallback (useResourceCache) so Hugo serves pre-built output when the tool is missing.

Example fix

// before
$ hugo
ERROR: tocss-dart: failed to transform ... You need to install Dart Sass

// after
$ npm install -g sass
$ hugo

// Feature matrix check: ensure each used transformer's tool is installed.
func pipelineDepsInstalled(kind string) bool {
    switch kind {
    case "postcss": _, e := exec.LookPath("postcss"); return e == nil
    case "tailwindcss": _, e := exec.LookPath("tailwindcss"); return e == nil
    case "tocss-dart": _, e := exec.LookPath("sass"); return e == nil
    case "babel": _, e := exec.LookPath("babel"); return e == nil
    }
    return true
}

When it happens

Trigger: Calling a pipeline transformation whose required external tool is absent: PostCSS without postcss-cli, TailwindCSS without the CLI, tocss-dart without Dart Sass, babel without @babel/cli, or libsass tocss on a non-extended Hugo build. The underlying transformer returns ErrFeatureNotAvailable / FeatureNotAvailableError.

Common situations: CI without node_modules, minimal Docker image, new dev machine without `npm install`, deploying a theme that bundles postcss/tailwind steps, or using the non-extended Hugo binary for SCSS.

Related errors

• babel config %q not found
• postcss config %q not found
• could not find %q in the import context
• %s: failed to transform %q (%s): %w
• resource %q not found in file cache

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