Hugo Pipes Asset Failures: Diagnose Missing CSS/JS and Fingerprint Mismatches

Recognizable condition

The built site loads with empty styles or scripts. In the browser you see blank src or href attributes, 404s for /assets/..., or console errors for CSS/JS while the source files exist under assets/. The problem is specific to Hugo Pipes processing, not content rendering.

Useful takeaway: when Pipes returns nil or fails to transpile, Hugo still builds, so the site looks broken only after publish. Check resource resolution before blaming the host.

Cause to symptom table

Ordered checks

1. Confirm file location. Run from the site root. Verify the file exists under assets/, not static/. Example path: assets/scss/main.scss. Permission needed: read access to the repo.

2. Surface build errors. Run hugo --minify in the site root. This forces Pipes evaluation and prints pipeline errors that hugo server may hide. Expected check: no "error calling" messages for resources.

3. Check edition and config. Run hugo version and hugo env from the site root. Confirm extended edition is installed if you use Sass/SCSS or ESBuild/TypeScript. Inspect effective config for baseURL and publishDir in hugo.toml or config.toml. Risk: changing baseURL changes all asset URLs.

4. Test resource resolution in a template. Insert a temporary snippet in a layout to print the resource:

   {{ $r := resources.Get "scss/main.scss" }}{{ printf "%#v" $r }}

   Build the site. If the output is nil, the path is wrong. Remove the snippet after verification.

5. Confirm transpilers on PATH. For external dart-sass or esbuild setups, ensure the binaries are available to the build process. With Hugo extended, built-in processing should be used instead of external tools.

Fixes tied to findings

resource.Get returns nil

Correct the asset path and ensure the file is under assets/. Use the path relative to assets/ without leading slash. Example template pattern:

{{ $style := resources.Get "scss/main.scss" | toCSS | minify | resources.Fingerprint "sha256" }}

Do not hardcode fingerprinted URLs. Generate them each build.

Unsupported format or missing transpiler

If you need Sass/SCSS or TypeScript, use Hugo extended edition. Avoid calling toCSS on plain CSS. For JS, prefer built-in processing with js.Build rather than external esbuild unless required.

baseURL or publishDir mismatch

Align baseURL with the deployment host and keep publishDir consistent between local and CI. Fingerprinted URLs are absolute based on baseURL. Changing publishDir changes where files are written, not served.

Nil pipeline chain

Guard the pipeline. Only fingerprint when resource is non-nil:

{{ with resources.Get "scss/main.scss" }}{{ $style := . | toCSS | minify | resources.Fingerprint }}{{ end }}

This prevents build errors when a file is temporarily missing.

How to verify the fix

Create a minimal reproduction: one file assets/scss/main.scss and a layout using resources.Get with toCSS and Fingerprint. Build with hugo --minify and inspect public/ for the generated CSS file and a matching href in the HTML. Check that the href is not empty and points inside the publish directory.

Run hugo version and hugo env to confirm edition and effective config values before and after changes.

Escalation criteria

• Error persists after path correction and edition verification.
• Failure appears only in production CI but not locally with the same config.
• Issue involves custom output formats or multilingual output paths where assets are duplicated per language.

Before escalating, collect Hugo version output, the relevant hugo.toml sections for baseURL, publishDir, and any Pipes configuration, plus a minimal site reproducing the nil resource or transpilation failure.

Limitations

This guide assumes static file deployment to a web host, not development server behavior alone. Fingerprinted asset URLs change between builds; avoid caching layers that hardcode them. Configuration keys and defaults vary across Hugo releases; verify keys against your installed release rather than older tutorials. Hugo extended edition is required for Sass/SCSS and ESBuild/TypeScript processing; the standard build lacks these transpilers.