gohugoio/hugo · error

%s: failed to transform %q (%s): %w

Error message

%s: failed to transform %q (%s): %w

What it means

Wrapper produced by Spec.Transform's newErr for any non-FeatureNotAvailable transformation error. It formats '<NAME>: failed to transform "<path>" (<mediatype>): <cause>'. This is the generic 'the transformer ran but returned an error' wrapper; the real cause is in %w.

Source

Thrown at resources/transform.go:599

				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)
			}
			if err != nil && !tryFileCache {
				return nil, newErr(err)
			}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Read the wrapped %w cause — it is the actual transformer error and usually names the file, line, and reason.
2. Fix the source asset / config reported by the inner error.
3. If the inner error is itself opaque, run `hugo -v` or check the resource cache key path to isolate which transformation in the chain failed.

Example fix

// before: SCSS syntax error
$primary: #333
.nav { color: $primary }

// after (fixed missing semicolon)
$primary: #333;
.nav { color: $primary; }

// Wrap Transform and surface the wrapped cause for actionable logging.
r, err := res.Transform(t)
if err != nil {
    return nil, fmt.Errorf("transform failed for %s: %w", res.Path(), err)
}

// Unwrap to inspect FeatureNotAvailableError vs concrete error.
if err != nil {
    var fna *herrors.FeatureNotAvailableError
    switch {
    case errors.As(err, &fna): /* install missing tool */
    default: /* fix source per inner error */
    }
}

When it happens

Trigger: A pipeline transformer (e.g. esbuild js.Build, tocss, minify, postcss with bad input) executes and returns a concrete error that is not a feature-not-available error. newErr wraps it with the transformation name, input path, and media type.

Common situations: SCSS/JS syntax errors during compilation, esbuild errors, postcss plugin errors, a broken custom output extension, or content that fails a downstream transform for any reason.

Related errors

• %s: failed to transform %q (%s) <errMsg>: %w
• failed to detect format from content
• failed to detect target data serialization format
• transform.Highlight: expects at most 3 arguments
• must provide at least one argument

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