{"record":{"id":"bf0c82cd46634203","repo":"gohugoio/hugo","slug":"s-failed-to-transform-q-s-errmsg-w","errorCode":null,"errorMessage":"%s: failed to transform %q (%s) <errMsg>: %w","messagePattern":"(.+?): failed to transform %q \\((.+?)\\) <errMsg>: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/transform.go","lineNumber":596,"sourceCode":"\t\t\tif herrors.IsFeatureNotAvailableError(err) {\n\t\t\t\tvar errMsg string\n\t\t\t\tswitch strings.ToLower(tr.Key().Name) {\n\t\t\t\tcase \"postcss\":\n\t\t\t\t\t// This transformation is not available in this\n\t\t\t\t\t// Most likely because PostCSS is not installed.\n\t\t\t\t\terrMsg = \". You need to install PostCSS. See https://gohugo.io/functions/css/postcss/\"\n\t\t\t\tcase \"tailwindcss\":\n\t\t\t\t\terrMsg = \". You need to install TailwindCSS CLI. See https://gohugo.io/functions/css/tailwindcss/\"\n\t\t\t\tcase \"tocss\":\n\t\t\t\t\terrMsg = \". Check your Hugo installation; you need the extended version to build SCSS/SASS with transpiler set to 'libsass'.\"\n\t\t\t\tcase \"tocss-dart\":\n\t\t\t\t\terrMsg = \". You need to install Dart Sass, see https://gohugo.io//functions/css/sass/#dart-sass\"\n\t\t\t\tcase \"babel\":\n\t\t\t\t\terrMsg = \". You need to install Babel, see https://gohugo.io/functions/js/babel/\"\n\n\t\t\t\t}\n\n\t\t\t\treturn fmt.Errorf(msg+errMsg+\": %w\", err)\n\t\t\t}\n\n\t\t\treturn fmt.Errorf(msg+\": %w\", err)\n\t\t}\n\n\t\tbcfg := r.spec.BuildConfig()\n\t\tvar tryFileCache bool\n\t\tif mayBeCachedOnDisk && bcfg.UseResourceCache(nil) {\n\t\t\ttryFileCache = true\n\t\t} else {\n\t\t\terr = tr.Transform(tctx)\n\t\t\tif err != nil && err != herrors.ErrFeatureNotAvailable {\n\t\t\t\treturn nil, newErr(err)\n\t\t\t}\n\n\t\t\tif mayBeCachedOnDisk {\n\t\t\t\ttryFileCache = bcfg.UseResourceCache(err)\n\t\t\t}","sourceCodeStart":578,"sourceCodeEnd":614,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/transform.go#L578-L614","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Run `hugo --gc` or `npm ci` to ensure deps are present before building.","If you intentionally pre-build assets, enable disk cache fallback (useResourceCache) so Hugo serves pre-built output when the tool is missing."],"exampleFix":"// before\n$ hugo\nERROR: tocss-dart: failed to transform ... You need to install Dart Sass\n\n// after\n$ npm install -g sass\n$ hugo","handlingStrategy":"validation","validationCode":"// Feature matrix check: ensure each used transformer's tool is installed.\nfunc pipelineDepsInstalled(kind string) bool {\n    switch kind {\n    case \"postcss\": _, e := exec.LookPath(\"postcss\"); return e == nil\n    case \"tailwindcss\": _, e := exec.LookPath(\"tailwindcss\"); return e == nil\n    case \"tocss-dart\": _, e := exec.LookPath(\"sass\"); return e == nil\n    case \"babel\": _, e := exec.LookPath(\"babel\"); return e == nil\n    }\n    return true\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run `npm ci` (with package-lock) in CI before `hugo`.","Document required toolchain per project; fail CI early with explicit checks.","For deploy-only environments, commit resources/_gen prebuilt output and set useResourceCache=always."],"tags":["transform","feature-not-available","asset-pipeline","toolchain","postcss","babel","tailwind","dart-sass"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}