{"record":{"id":"2c3246b7a3c82ccd","repo":"gohugoio/hugo","slug":"postprocess-w","errorCode":null,"errorMessage":"postProcess: %w","messagePattern":"postProcess: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"hugolib/hugo_sites_build.go","lineNumber":222,"sourceCode":"\t\t\treturn err\n\t\t}\n\n\t\t// We need to do this before render deferred.\n\t\tif err := h.printPathWarningsOnce(); err != nil {\n\t\t\th.SendError(fmt.Errorf(\"printPathWarnings: %w\", err))\n\t\t}\n\n\t\tif err := h.renderDeferred(infol); err != nil {\n\t\t\th.SendError(fmt.Errorf(\"renderDeferred: %w\", err))\n\t\t}\n\n\t\t// This needs to be done after the deferred rendering to get complete template usage coverage.\n\t\tif err := h.printUnusedTemplatesOnce(); err != nil {\n\t\t\th.SendError(fmt.Errorf(\"printPathWarnings: %w\", err))\n\t\t}\n\n\t\tif err := h.postProcess(infol); err != nil {\n\t\t\th.SendError(fmt.Errorf(\"postProcess: %w\", err))\n\t\t}\n\t}\n\n\tif h.Metrics != nil {\n\t\tvar b bytes.Buffer\n\t\th.Metrics.WriteMetrics(&b)\n\n\t\th.Log.Printf(\"\\nTemplate Metrics:\\n\\n\")\n\t\th.Log.Println(b.String())\n\t}\n\n\th.StopErrorCollector()\n\n\terr := <-errs\n\tif err != nil {\n\t\treturn err\n\t}\n","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/gohugoio/hugo/blob/52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2/hugolib/hugo_sites_build.go#L204-L240","documentation":"Hugo wraps this around any failure in the post-processing build pass (HugoSites.postProcess), which runs after all pages are rendered. That pass writes the jsconfig.json for JS IntelliSense, and — more importantly — resolves every resource flagged for post-publish: deferred asset transforms (toCSS, PostCSS, babel, minify) and per-page resource publishing that were deferred during render. The %w carries the real underlying cause, so this string is only the outer label for a pipeline/publish failure.","triggerScenarios":"An asset pipeline resource (resources.PostCSS, resources.ToCSS, js.Build, babel) cannot complete; an image/resource fails its Publish() call; a deferred post-process placeholder in rendered HTML cannot be resolved; a post-publish Resource.Publisher returns an error. Emitted at hugo_sites_build.go:222 via h.SendError.","commonSituations":"postcss-cli / dart-sass / esbuild not installed or not on PATH; node_modules missing (forgot `npm install`); a broken or non-existent asset input path passed to a transform; publishing into a read-only or locked output directory; a template uses `.RelPermalink` on a resource whose transform failed earlier and was deferred.","solutions":["Read the wrapped error after the colon — the %w is the actual cause (e.g. 'postcss: command not found', 'file does not exist').","Install/verify the external binary the transform needs: `npm i -D postcss postcss-cli` (or dart-sass / esbuild) and ensure it resolves on PATH.","Run `npm install` in the project root so node_modules the pipeline imports exist.","Confirm the asset source path passed to the pipeline exists and is readable.","Check the output/publish directory is writable and not locked by another process."],"exampleFix":"// before\n{{ $css := resources.Get \"css/main.scss\" | toCSS }}\n// postProcess error if postcss/sass binary missing\n\n// after: ensure toolchain present\n//   npm i -D postcss postcss-cli   (or dart-sass for scss)\n{{ $css := resources.Get \"css/main.scss\" | css.Sass }}","handlingStrategy":"try-catch","validationCode":"// Pre-build: verify external toolchain the pipeline needs exists\nimport \"os/exec\"\nfunc toolReady(name string) bool { _, err := exec.LookPath(name); return err == nil }\n// if !toolReady(\"postcss\") { return fmt.Errorf(\"install postcss-cli\") }","typeGuard":null,"tryCatchPattern":"if err := sites.Build(cfg); err != nil {\n    var pe *hugofs.PathError\n    if errors.As(err, &pe) { /* file/permission cause */ }\n    return err // surface wrapped postProcess cause to the user\n}","preventionTips":["Pin and install every asset toolchain (postcss-cli, dart-sass, esbuild) the templates reference.","Run `npm install` in CI before `hugo` so node_modules exist.","Make the publish/output directory writable."],"tags":["build","asset-pipeline","postprocess","publish"],"backgroundTag":null,"analyzedSha":"52c9bd7908b4d02d4d0ff8f82a888834d6ee10d2","analyzedAt":"2026-08-09T21:49:36.660Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}