gohugoio/hugo · error

resource not found in file cache

Error message

resource %q not found in file cache

What it means

Returned by Spec.Transform when a transformation was skipped/deferred to the on-disk file cache (tryFileCache path, e.g. because useResourceCache is enabled or the tool was unavailable) but no cached file exists for the transformation key. newErr wraps a fresh error 'resource "<key>" not found in file cache'.

Solutions

1. Run the build once on a machine that has the required tool installed (postcss/babel/dart-sass) so the cache entry is generated.
2. Commit/copy the resources/_gen directory to the environment that lacks the tool, or ensure useResourceCache ('always'/'never') matches your intent.
3. Install the missing tool so the transformation runs live instead of relying on the cache.

Example fix

// before: cache missing in CI
$ hugo  // resource "postcss/..." not found in file cache

// after: generate cache locally then ship it
$ hugo --gc                       // locally, with postcss installed
$ git add resources/_gen          // commit prebuilt artifacts
$ CI runs hugo                    // uses the cache

// Ensure the cache entry exists for a transform key before relying on cache.
func cacheEntryExists(cacheDir, key string) bool {
    p := filepath.Join(cacheDir, "resources", key)
    _, err := os.Stat(p)
    return err == nil
}

When it happens

Trigger: The build is configured (or falls back) to read transformed resources from the file cache (resources/_gen), but the cache entry for the given transformation key is missing — typically because a tool was unavailable and no prior successful build populated the cache.

Common situations: Deploying to CI where the asset tool isn't installed and the prebuilt cache wasn't committed/copied; clearing the resources/_gen directory; changing transformation options so the cache key no longer matches a previously built artifact.

Related errors

• : failed to transform ( )
• babel config not found
• cache dir contains unresolved placeholders
• could not find in the import context
• esbuild: entry point output not found

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/5b7ccdd5616c1e6f. Report an issue: GitHub.

Appendix: source

Thrown at resources/transform.go:626

			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 52c9bd7908)