{"id":"5b7ccdd5616c1e6f","repo":"gohugoio/hugo","slug":"resource-q-not-found-in-file-cache","errorCode":null,"errorMessage":"resource %q not found in file cache","messagePattern":"resource %q not found in file cache","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"resources/transform.go","lineNumber":625,"sourceCode":"\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}\n\t\t}\n\n\t\tif tryFileCache {\n\t\t\tf := r.target.tryTransformedFileCache(key, updates)\n\t\t\tif f == nil {\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn nil, newErr(err)\n\t\t\t\t}\n\t\t\t\treturn nil, newErr(fmt.Errorf(\"resource %q not found in file cache\", key))\n\t\t\t}\n\t\t\ttransformedContentr = f\n\t\t\tupdates.sourceFs = cache.fileCache.Fs\n\t\t\tdefer f.Close()\n\n\t\t\t// The reader above is all we need.\n\t\t\tbreak\n\t\t}\n\n\t\tif tctx.OutPath != \"\" {\n\t\t\ttctx.InPath = tctx.OutPath\n\t\t\ttctx.OutPath = \"\"\n\t\t}\n\t}\n\n\tif transformedContentr == nil {\n\t\tupdates.updateFromCtx(tctx)\n\t}","sourceCodeStart":607,"sourceCodeEnd":643,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/resources/transform.go#L607-L643","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before — CI, dart-sass not installed; build fails on cache miss\n- run: hugo --minify\n\n# after\n- run: npm install -g sass\n- run: hugo --minify","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"// cache-miss during transform: clear caches and rebuild rather than retrying in-process\n// shell: hugo --gc  (or delete resources/_gen) then rebuild","preventionTips":["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"],"tags":["hugo","resource-pipeline","file-cache","build-error","ci"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}