What causes "resource %q not found in file cache" in gohugoio/hugo?

Look for the real transformation error in the surrounding build output — this message is usually the fallback, not the root cause; fix that failure first.

gohugoio/hugo · error

resource %q not found in file cache

Error message

resource %q not found in file cache

What it means

Hugo's resource transformation pipeline in resources/transform.go can serve a transformed resource from the on-disk file cache instead of recomputing it. When the transformation either failed or was skipped and Hugo falls back to the cache (`tryFileCache`), a missing cache entry for the computed key produces this error. It usually surfaces as the visible symptom of an underlying transformation failure whose error was swallowed in favor of the cache lookup.

Source

Thrown at resources/transform.go:625

			if err != nil && err != herrors.ErrFeatureNotAvailable {
				return nil, newErr(err)
			}

			if mayBeCachedOnDisk {
				tryFileCache = bcfg.UseResourceCache(err)
			}
			if err != nil && !tryFileCache {
				return nil, newErr(err)
			}
		}

		if tryFileCache {
			f := r.target.tryTransformedFileCache(key, updates)
			if f == nil {
				if err != nil {
					return nil, newErr(err)
				}
				return nil, newErr(fmt.Errorf("resource %q not found in file cache", key))
			}
			transformedContentr = f
			updates.sourceFs = cache.fileCache.Fs
			defer f.Close()

			// The reader above is all we need.
			break
		}

		if tctx.OutPath != "" {
			tctx.InPath = tctx.OutPath
			tctx.OutPath = ""
		}
	}

	if transformedContentr == nil {
		updates.updateFromCtx(tctx)
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Look for the real transformation error in the surrounding build output — this message is usually the fallback, not the root cause; fix that failure first.
Ensure the tool the pipeline needs is installed on the build machine (e.g. `dart-sass` on PATH for `css.Sass`, Node + `postcss-cli` for `css.PostCSS`).
Commit or restore the `resources/_gen` directory in CI if you rely on the resource cache, or disable the cache fallback so the underlying error is reported directly.
Clear stale caches with `hugo --gc` and rebuild fully after a Hugo upgrade so cache keys are regenerated.
Check `[caches]` in hugo.toml — a `:cacheDir`/`:resourceDir` that isn't writable or is wiped between steps will make every cache lookup miss.

Example fix

# before — CI, dart-sass not installed; build fails on cache miss
- run: hugo --minify

# after
- run: npm install -g sass
- run: hugo --minify

Defensive patterns

Strategy: retry

Try / catch

// cache-miss during transform: clear caches and rebuild rather than retrying in-process
// shell: hugo --gc  (or delete resources/_gen) then rebuild

Prevention

Don't manually edit or partially delete the resources/_gen or file cache directories
In CI, cache the whole cache directory atomically or not at all
Run hugo --gc periodically; on this error, wipe the cache and rebuild once
Avoid concurrent hugo processes sharing one cacheDir

When it happens

Trigger: Running a build where a pipeline step (Dart Sass/SCSS, PostCSS, esbuild/js.Build, babel, minify, resources.PostProcess) fails or its binary is unavailable, and `useResourceCache` is enabled (commonly `--enableGitInfo`-style CI setups, `HUGO_ENABLE_RESOURCE_CACHE`, or offline/`--ignoreCache=false` builds) so Hugo tries `resources/_gen` and finds nothing for that key.

Common situations: CI builds where `resources/_gen` is gitignored or not restored from cache, so the fallback has nothing to fall back to; a missing external binary (dart-sass, postcss-cli, node) on the build machine; after `hugo --gc` or a manual clear of the cache directory; a Hugo version bump changing the cache key so previously cached entries no longer match.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/5b7ccdd5616c1e6f.json. Report an issue: GitHub ↗.