{"record":{"id":"93c3c6d5145bb0ad","repo":"gohugoio/hugo","slug":"s-failed-to-transform-q-s-w","errorCode":null,"errorMessage":"%s: failed to transform %q (%s): %w","messagePattern":"(.+?): failed to transform %q \\((.+?)\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/transform.go","lineNumber":599,"sourceCode":"\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}\n\t\t\tif err != nil && !tryFileCache {\n\t\t\t\treturn nil, newErr(err)\n\t\t\t}","sourceCodeStart":581,"sourceCodeEnd":617,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/resources/transform.go#L581-L617","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped %w cause — it is the actual transformer error and usually names the file, line, and reason.","Fix the source asset / config reported by the inner error.","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."],"exampleFix":"// before: SCSS syntax error\n$primary: #333\n.nav { color: $primary }\n\n// after (fixed missing semicolon)\n$primary: #333;\n.nav { color: $primary; }","handlingStrategy":"try-catch","validationCode":"// Wrap Transform and surface the wrapped cause for actionable logging.\nr, err := res.Transform(t)\nif err != nil {\n    return nil, fmt.Errorf(\"transform failed for %s: %w\", res.Path(), err)\n}","typeGuard":null,"tryCatchPattern":"// Unwrap to inspect FeatureNotAvailableError vs concrete error.\nif err != nil {\n    var fna *herrors.FeatureNotAvailableError\n    switch {\n    case errors.As(err, &fna): /* install missing tool */\n    default: /* fix source per inner error */\n    }\n}","preventionTips":["Always inspect the wrapped %w cause, not just the outer message.","Build incrementally (`hugo --renderToMemory`) to isolate which transform fails.","Keep tool versions pinned and source assets linted."],"tags":["transform","build-failure","asset-pipeline","wrapper"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}