Backtestshugorun-20261005-133023#15101

Issue #15101 Merged fix PR # Run 5 Oct 2026 · run-20261005-133023 gohugoio/hugo

hugo --gc deletes in-use image cache files when on-disk path case differs from the cache key (case-insensitive filesystems)

Better

Our patch was judged better than the merged fix.

In this judgment, Patch A = our agent, Patch B = the merged fix.

Both patches fix the root cause: the pruner's case-sensitive `seen.Has(name)` check. Both keep correct behavior on case-sensitive filesystems.

Patch A asks the filesystem directly. When the exact check fails, it looks up seen IDs by lowercase name, stats each one, and uses `os.SameFile` to confirm it is the same on-disk entry. This mirrors how the filesystem resolved the read during the build, which is what the issue asks for. It works on any case-insensitive filesystem without relying on walk-order or presence heuristics. On case-sensitive filesystems, a differently-cased stale file is still pruned. The lowercase index is built lazily, so there is no cost when everything matches. The one risk is the `unwrapFileInfo` helper: if the production filecache Fs wrapped FileInfo in some unexpected way, `SameFile` would return false. That would fall back to the old behavior, which is safe but unfixed. The test uses a hugofs decorator to cover this. The error return from `isSeen` is always nil, a minor wart.

Patch B infers sameness indirectly. A lowercase-matching name is deferred, and it is removed only if the exact-case key was also visited during the walk. This gives the right result in the reported scenario. It is a heuristic rather than a direct identity check, though. Lowercase collisions in `seenByLower` (two IDs differing only by case) silently keep only one. It also restructures the walk's removal logic more broadly.

On tests, Patch A's key case-insensitive test runs on every platform: it simulates case-insensitivity with a hard link. So it actually exercises the fix in Linux CI and would fail before the change. Patch B's case-insensitive unit test and testscript both skip on case-sensitive filesystems, so in typical CI only the MemMapFs case-sensitive test runs, and that path passed before the change too. B's end-to-end testscript is realistic. However, it brings extra infrastructure: a new `htesting` helper, a testscript `Condition` hook, and a `base64decode` command. That is more churn for a test that rarely runs.

Overall, A is more precise and better tested in practice, and B adds more scope for a heuristic fix.

The judge saw only the two patches, labelled A and B in random order, with issue links and version numbers removed. The reasoning above is shown verbatim.

Solve

2h 50m

Wall-clock time in the container

Full test suite

No new failures

3,679 passed · 95 skipped · 3,785 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

156vs 230 merged

Changed lines, ours vs merged

What happens

On a case-insensitive filesystem (macOS APFS, Windows), hugo --gc deletes image cache files under resources/_gen that the build actively uses, if the on-disk path case differs from the cache key. The build itself works fine (the case-insensitive filesystem resolves the read), but the pruner's usage check is a case-sensitive string comparison, so the just-used file is considered unused and removed.

The relevant code is in cache/filecache/filecache_pruner.go (unchanged on master):

if !shouldRemove && c.entryLocker.seen.Len() > 0 {
    // Remove it if it's not been touched/used in the last build.
    shouldRemove = !c.entryLocker.seen.Has(name)
}

seen contains the cache key (for images: the lowercased target path, via ImageCache.getOrCreate → c.fcache.ReadOrCreate(relTargetPath, …)), while name is the real on-disk name from the filesystem walk. If they differ only in case, seen.Has(name) is false and the file is deleted.

Why the case can differ in practice

Page paths have been lowercased since the v0.123 page-system rewrite, so cache keys for page-bundle images are lowercase. Caches created by older Hugo versions preserve the source directory case (e.g. resources/_gen/images/collections/PastFuture/…). Such caches are common in the wild: committed to git for CI cold-start speed, restored by CI cache plugins, or simply carried forward on a developer machine across Hugo upgrades.

The result is a permanent rebuild/evict cycle: --gc deletes the in-use entries → the next build silently re-processes all of them → the new files land inside the surviving mixed-case directory (the prune walk visits directories before deleting their files, so the directory is never seen empty and survives; on a case-insensitive filesystem the re-created file then lands in it) → the next --gc deletes them again. On the real site where we found this, every build re-scaled 267 images (~35 s per build, forever).

Minimal reproduction (macOS)

hugo new site repro && cd repro
mkdir -p content/MyBundle layouts/_default
printf 'baseURL = "https://example.org/"\ndisableKinds = ["taxonomy", "term", "rss", "sitemap"]\n' > hugo.toml
printf -- '---\ntitle: My Bundle\n---\n' > content/MyBundle/index.md
cp /path/to/any.jpeg content/MyBundle/cover.jpeg
printf '{{ with .Resources.GetMatch "cover.jpeg" }}{{ with .Resize "100x" }}<img src="{{ .RelPermalink }}">{{ end }}{{ end }}' > layouts/_default/single.html
printf 'home' > layouts/_default/home.html

hugo                      # creates resources/_gen/images/mybundle/cover_hu_<hash>.jpeg
# simulate a cache written by an older Hugo (or copied from elsewhere):
mv resources/_gen/images/mybundle resources/_gen/images/tmp
mv resources/_gen/images/tmp resources/_gen/images/MyBundle

hugo --gc                 # build succeeds (16 ms, cache hit), but reports "Cleaned 1"
find resources -type f    # -> empty: the file the build just used is gone

hugo                      # re-processes the image (474 ms) — and writes it back
                          # into the surviving MyBundle/ dir, so the cycle repeats

Observed output of the --gc build:

Processed images │  1
Cleaned          │  1
Total in 16 ms

A cache file that was read 16 ms earlier is deleted as "not been touched/used in the last build".

What I expected

--gc should never delete a cache entry that the same build read. On case-insensitive filesystems the usage check should match the way the filesystem resolved the read — e.g. compare case-insensitively (or normalize walk names against the seen set) when the cache filesystem is case-insensitive. Renaming the on-disk entry to the key's case would even self-heal old caches.

Version

hugo v0.164.0+extended+withdeploy darwin/arm64 BuildDate=2026-07-06T16:39:30Z VendorInfo=Homebrew

The pruner code is identical on current master.

The two patches

Our patch+155 −1
cache/filecache/filecache_pruner.goindex d6322cb70..757ae6bd9 100644@@ -16,7 +16,9 @@ package filecache import ( 	"fmt" 	"io"+	iofs "io/fs" 	"os"+	"strings"  	"github.com/gohugoio/hugo/common/herrors" 	"github.com/gohugoio/hugo/hugofs"@@ -59,6 +61,38 @@ func (c *Cache) Prune(force bool) (int, error) {  	counter := 0 +	// Lazily built index of the seen IDs keyed by their lower case form,+	// used to match entries on case-insensitive filesystems.+	var seenLower map[string][]string++	isSeen := func(name string, info os.FileInfo) (bool, error) {+		if c.entryLocker.seen.Has(name) {+			return true, nil+		}+		if seenLower == nil {+			seenLower = make(map[string][]string)+			for id := range c.entryLocker.seen.All() {+				k := strings.ToLower(id)+				seenLower[k] = append(seenLower[k], id)+			}+		}+		// On case-insensitive filesystems (e.g. macOS, Windows) the ID used in the+		// build may resolve to an on-disk name with different casing,+		// e.g. a cache written by an older Hugo version.+		// Ask the filesystem whether they are the same file.+		for _, id := range seenLower[strings.ToLower(name)] {+			fi, err := c.Fs.Stat(id)+			if err != nil {+				// Not resolvable, so not the same file.+				continue+			}+			if os.SameFile(unwrapFileInfo(info), unwrapFileInfo(fi)) {+				return true, nil+			}+		}+		return false, nil+	}+ 	err := afero.Walk(c.Fs, "", func(name string, info os.FileInfo, err error) error { 		if info == nil { 			return nil@@ -95,7 +129,11 @@ func (c *Cache) Prune(force bool) (int, error) {  		if !shouldRemove && c.entryLocker.seen.Len() > 0 { 			// Remove it if it's not been touched/used in the last build.-			shouldRemove = !c.entryLocker.seen.Has(name)+			seen, err := isSeen(name, info)+			if err != nil {+				return err+			}+			shouldRemove = !seen 		}  		if shouldRemove {@@ -116,6 +154,22 @@ func (c *Cache) Prune(force bool) (int, error) { 	return counter, err } +// unwrapFileInfo returns the underlying os.FileInfo of fi, which may be wrapped+// by the hugofs decorators, so it can be used with os.SameFile.+func unwrapFileInfo(fi os.FileInfo) os.FileInfo {+	for {+		de, ok := fi.(iofs.DirEntry)+		if !ok {+			return fi+		}+		ufi, err := de.Info()+		if err != nil || ufi == nil || ufi == fi {+			return fi+		}+		fi = ufi+	}+}+ func (c *Cache) pruneRootDirs(force bool) (int, error) { 	dirs, err := afero.ReadDir(c.Fs, "") 	if err != nil {cache/filecache/filecache_pruner_test.goindex 117ff3430..be3ac3860 100644@@ -15,11 +15,14 @@ package filecache_test  import ( 	"fmt"+	"os"+	"path/filepath" 	"testing" 	"testing/synctest" 	"time"  	"github.com/gohugoio/hugo/cache/filecache"+	"github.com/gohugoio/hugo/hugofs" 	"github.com/spf13/afero"  	qt "github.com/frankban/quicktest"@@ -113,3 +116,100 @@ dir = ":resourceDir/_gen" 		} 	}) }++// Issue: --gc deleted in-use cache entries on case-insensitive filesystems+// when the on-disk path case differed from the cache key.+func TestPruneCaseInsensitiveFilesystem(t *testing.T) {+	t.Parallel()+	c := qt.New(t)++	dir := t.TempDir()+	cfg := filecache.FileCacheConfig{+		MaxAge: 100 * time.Hour,+		Dir:    dir,+	}++	// Cache entries written with mixed case, e.g. by an older Hugo version.+	writeFile := func(name, content string) {+		filename := filepath.Join(dir, filepath.FromSlash(name))+		c.Assert(os.MkdirAll(filepath.Dir(filename), 0o777), qt.IsNil)+		c.Assert(os.WriteFile(filename, []byte(content), 0o666), qt.IsNil)+	}+	writeFile("images/MyBundle/cover_hu_123.jpg", "cached")+	writeFile("images/MyBundle/unused_hu_456.jpg", "unused")++	exists := func(name string) bool {+		_, err := os.Stat(filepath.Join(dir, filepath.FromSlash(name)))+		return err == nil+	}++	// Make the lower case key resolve to the same file as the mixed case+	// on-disk name, as a case-insensitive filesystem does.+	// On case-sensitive filesystems, simulate it with a hard link.+	const usedID = "images/mybundle/cover_hu_123.jpg"+	if !exists(usedID) {+		c.Assert(os.MkdirAll(filepath.Join(dir, "images", "mybundle"), 0o777), qt.IsNil)+		c.Assert(os.Link(+			filepath.Join(dir, "images", "MyBundle", "cover_hu_123.jpg"),+			filepath.Join(dir, "images", "mybundle", "cover_hu_123.jpg"),+		), qt.IsNil)+	}++	cache := filecache.NewCache(hugofs.NewBasePathFs(hugofs.NewBaseFileDecorator(afero.NewOsFs()), dir), cfg)+	_, b, err := cache.GetOrCreateBytes(usedID, func() ([]byte, error) {+		return []byte("created"), nil+	})+	c.Assert(err, qt.IsNil)+	c.Assert(string(b), qt.Equals, "cached")++	count, err := cache.Prune(false)+	c.Assert(err, qt.IsNil)+	c.Assert(count, qt.Equals, 1)++	c.Assert(exists("images/MyBundle/cover_hu_123.jpg"), qt.IsTrue)+	c.Assert(exists(usedID), qt.IsTrue)+	c.Assert(exists("images/MyBundle/unused_hu_456.jpg"), qt.IsFalse)++	// The entry is still served from the cache.+	_, b, err = cache.GetOrCreateBytes(usedID, func() ([]byte, error) {+		return []byte("created"), nil+	})+	c.Assert(err, qt.IsNil)+	c.Assert(string(b), qt.Equals, "cached")+}++// On case-sensitive filesystems, a stale entry differing only in case from a+// used key is a different file and should still be pruned.+func TestPruneCaseSensitiveFilesystemRemovesStale(t *testing.T) {+	t.Parallel()+	c := qt.New(t)++	dir := t.TempDir()+	staleFilename := filepath.Join(dir, "images", "MyBundle", "cover_hu_123.jpg")+	c.Assert(os.MkdirAll(filepath.Dir(staleFilename), 0o777), qt.IsNil)+	c.Assert(os.WriteFile(staleFilename, []byte("stale"), 0o666), qt.IsNil)++	const usedID = "images/mybundle/cover_hu_123.jpg"+	if _, err := os.Stat(filepath.Join(dir, filepath.FromSlash(usedID))); err == nil {+		t.Skip("filesystem is case-insensitive")+	}++	cache := filecache.NewCache(hugofs.NewBasePathFs(hugofs.NewBaseFileDecorator(afero.NewOsFs()), dir), filecache.FileCacheConfig{+		MaxAge: 100 * time.Hour,+		Dir:    dir,+	})+	_, b, err := cache.GetOrCreateBytes(usedID, func() ([]byte, error) {+		return []byte("created"), nil+	})+	c.Assert(err, qt.IsNil)+	c.Assert(string(b), qt.Equals, "created")++	count, err := cache.Prune(false)+	c.Assert(err, qt.IsNil)+	c.Assert(count, qt.Equals, 1)++	_, err = os.Stat(staleFilename)+	c.Assert(os.IsNotExist(err), qt.IsTrue)+	_, err = os.Stat(filepath.Join(dir, filepath.FromSlash(usedID)))+	c.Assert(err, qt.IsNil)+} 
Merged fix · PR #+217 −13
cache/filecache/filecache_pruner.goindex d6322cb70..cd95766be 100644@@ -17,6 +17,7 @@ import ( 	"fmt" 	"io" 	"os"+	"strings"  	"github.com/gohugoio/hugo/common/herrors" 	"github.com/gohugoio/hugo/hugofs"@@ -59,6 +60,29 @@ func (c *Cache) Prune(force bool) (int, error) {  	counter := 0 +	seen := c.entryLocker.seen+	seenByLower := make(map[string]string, seen.Len())+	for id := range seen.All() {+		seenByLower[strings.ToLower(id)] = id+	}++	// Names on disk matching a used cache key except for the case, and the used keys+	// actually walked. See the note about case-insensitive filesystems below.+	var candidates map[string]string+	visited := make(map[string]bool, seen.Len())++	remove := func(name string) error {+		err := c.Fs.Remove(name)+		if err == nil {+			counter+++			return nil+		}+		if !herrors.IsNotExist(err) {+			return err+		}+		return nil+	}+ 	err := afero.Walk(c.Fs, "", func(name string, info os.FileInfo, err error) error { 		if info == nil { 			return nil@@ -93,27 +117,44 @@ func (c *Cache) Prune(force bool) (int, error) {  		shouldRemove := force || c.isExpired(info.ModTime()) -		if !shouldRemove && c.entryLocker.seen.Len() > 0 {-			// Remove it if it's not been touched/used in the last build.-			shouldRemove = !c.entryLocker.seen.Has(name)+		if seen.Has(name) {+			visited[name] = true+		} else if !shouldRemove && seen.Len() > 0 {+			if id, found := seenByLower[strings.ToLower(name)]; found {+				// On case-insensitive filesystems this is the same file as id; e.g. an+				// entry created before Hugo started lowercasing the content paths in+				// v0.123 (content/MyBundle => _gen/images/MyBundle). Decided once the+				// walk is done: if id is walked too, they are distinct files and this+				// one is stale. See issue 15101.+				if candidates == nil {+					candidates = make(map[string]string)+				}+				candidates[name] = id+			} else {+				// Remove it if it's not been touched/used in the last build.+				shouldRemove = true+			} 		}  		if shouldRemove {-			err := c.Fs.Remove(name)-			if err == nil {-				counter++-			}--			if err != nil && !herrors.IsNotExist(err) {-				return err-			}-+			return remove(name) 		}  		return nil 	})+	if err != nil {+		return counter, err+	}++	for name, id := range candidates {+		if visited[id] {+			if err := remove(name); err != nil {+				return counter, err+			}+		}+	} -	return counter, err+	return counter, nil }  func (c *Cache) pruneRootDirs(force bool) (int, error) {cache/filecache/filecache_pruner_test.goindex 117ff3430..dc01e417a 100644@@ -20,11 +20,72 @@ import ( 	"time"  	"github.com/gohugoio/hugo/cache/filecache"+	"github.com/gohugoio/hugo/htesting" 	"github.com/spf13/afero"  	qt "github.com/frankban/quicktest" ) +// A cache entry created before Hugo started lowercasing content paths in v0.123+// (e.g. _gen/images/MyBundle) is on a case-insensitive filesystem the same file as+// the lowercased cache key used today, and must not be pruned.+// See issue 15101.+func TestPruneCacheEntryWithOtherCase(t *testing.T) {+	t.Parallel()+	c := qt.New(t)++	dir := t.TempDir()+	if isCaseInsensitive, err := htesting.IsCaseInsensitiveFs(dir); err != nil {+		t.Fatal(err)+	} else if !isCaseInsensitive {+		t.Skip("skip test on case-sensitive filesystem")+	}++	fs := afero.NewBasePathFs(afero.NewOsFs(), dir)+	newCache := func() *filecache.Cache {+		return filecache.NewCache(fs, filecache.FileCacheConfig{Dir: "cache", MaxAge: -1})+	}++	c.Assert(newCache().SetBytes("MyBundle/i1", []byte("abc")), qt.IsNil)++	cache := newCache()+	_, b, err := cache.GetOrCreateBytes("mybundle/i1", func() ([]byte, error) {+		return []byte("def"), nil+	})+	c.Assert(err, qt.IsNil)+	c.Assert(string(b), qt.Equals, "abc")++	count, err := cache.Prune(false)+	c.Assert(err, qt.IsNil)+	c.Assert(count, qt.Equals, 0)+	c.Assert(cache.GetString("MyBundle/i1"), qt.Equals, "abc")+}++// On a case-sensitive filesystem the entries above are distinct files,+// and the one not used in this build should be pruned.+func TestPruneCacheEntryWithOtherCaseCaseSensitiveFs(t *testing.T) {+	t.Parallel()+	c := qt.New(t)++	fs := afero.NewMemMapFs()+	cache := filecache.NewCache(fs, filecache.FileCacheConfig{Dir: "cache", MaxAge: -1})++	c.Assert(cache.SetBytes("MyBundle/i1", []byte("abc")), qt.IsNil)++	cache = filecache.NewCache(fs, filecache.FileCacheConfig{Dir: "cache", MaxAge: -1})+	_, b, err := cache.GetOrCreateBytes("mybundle/i1", func() ([]byte, error) {+		return []byte("def"), nil+	})+	c.Assert(err, qt.IsNil)+	c.Assert(string(b), qt.Equals, "def")++	count, err := cache.Prune(false)+	c.Assert(err, qt.IsNil)+	c.Assert(count, qt.Equals, 1)+	c.Assert(cache.GetString("MyBundle/i1"), qt.Equals, "")+	c.Assert(cache.GetString("mybundle/i1"), qt.Equals, "def")+}+ func TestPrune(t *testing.T) { 	t.Parallel() htesting/test_helpers.goindex 384695df4..46f6bd9ec 100644@@ -16,6 +16,7 @@ package htesting import ( 	"math/rand" 	"os"+	"path/filepath" 	"regexp" 	"runtime" 	"strconv"@@ -58,6 +59,27 @@ func CreateTempDir(fs afero.Fs, prefix string) (string, func(), error) { 	return tempDir, func() { fs.RemoveAll(tempDir) }, nil } +// IsCaseInsensitiveFs reports whether dir lives on a case-insensitive filesystem+// (e.g. the default on macOS and Windows).+func IsCaseInsensitiveFs(dir string) (bool, error) {+	f, err := os.CreateTemp(dir, "case-*.tmp")+	if err != nil {+		return false, err+	}+	f.Close()+	defer os.Remove(f.Name())++	_, err = os.Stat(filepath.Join(dir, strings.ToUpper(filepath.Base(f.Name()))))+	if err != nil {+		if os.IsNotExist(err) {+			return false, nil+		}+		return false, err+	}++	return true, nil+}+ // BailOut panics with a stack trace after the given duration. Useful for // hanging tests. func BailOut(after time.Duration) {main_test.goindex 12e708dc0..8cea78818 100644@@ -15,6 +15,7 @@ package main  import ( 	"bytes"+	"encoding/base64" 	"encoding/json" 	"fmt" 	"io"@@ -27,6 +28,7 @@ import ( 	"runtime" 	"strconv" 	"strings"+	"sync" 	"testing" 	"time" @@ -78,10 +80,22 @@ func TestMain(m *testing.M) { 	}) } +var isCaseInsensitiveFs = sync.OnceValues(func() (bool, error) {+	return htesting.IsCaseInsensitiveFs(os.TempDir())+})+ var commonTestScriptsParam = testscript.Params{ 	Setup: func(env *testscript.Env) error { 		return testSetupFunc()(env) 	},+	Condition: func(cond string) (bool, error) {+		switch cond {+		case "caseinsensitivefs":+			return isCaseInsensitiveFs()+		default:+			return false, fmt.Errorf("unknown condition %q", cond)+		}+	}, 	Cmds: map[string]func(ts *testscript.TestScript, neg bool, args []string){ 		// log prints to stderr. 		"log": func(ts *testscript.TestScript, neg bool, args []string) {@@ -252,6 +266,34 @@ var commonTestScriptsParam = testscript.Params{ 				ts.Fatalf("failed to create symlink: %v", err) 			} 		},+		// base64decode decodes a base64-encoded file into a binary file.+		"base64decode": func(ts *testscript.TestScript, neg bool, args []string) {+			if len(args) != 2 {+				ts.Fatalf("usage: base64decode src_base64_file dest_binary_file")+			}++			// Resolve paths relative to the test sandbox's current directory+			src := ts.MkAbs(args[0])+			dest := ts.MkAbs(args[1])++			// Read the base64 text+			base64Data, err := os.ReadFile(src)+			if err != nil {+				ts.Fatalf("failed to read base64 file: %v", err)+			}++			// Decode base64 back to raw bytes.+			binaryBytes, err := base64.StdEncoding.DecodeString(strings.TrimSpace(string(base64Data)))+			if err != nil {+				ts.Fatalf("failed to decode base64 data: %v", err)+			}++			// Write the binary file.+			err = os.WriteFile(dest, binaryBytes, 0o644)+			if err != nil {+				ts.Fatalf("failed to write binary file: %v", err)+			}+		},  		// httpget checks that a HTTP resource's body matches (if it compiles as a regexp) or contains all of the strings given as arguments. 		"httpget": func(ts *testscript.TestScript, neg bool, args []string) {testscripts/commands/hugo_gc_mixed_case_cache_dir.txtnew file mode 100644index 000000000..7c7af1373@@ -0,0 +1,38 @@+# In Hugo v0.123 we started lowercasing the content paths, but on case-insensitive+# filesystems existing caches keep their mixed-case dir names (e.g. MyBundle).+# The pruner would then consider those entries unused and remove them on every+# hugo --gc. See issue 15101.++[!caseinsensitivefs] skip++base64decode pixel.png.txt content/MyBundle/pix.png++hugo++stdout 'Processed images │  1 '+tree resources/_gen+stdout 'pix_hu_a354833fd576551d.png'++# Simulate a cache created by an older Hugo version.+mv resources/_gen/images/mybundle resources/_gen/images/MyBundle++hugo --gc+stdout 'Cleaned          │  0 '++tree resources/_gen+stdout 'pix_hu_a354833fd576551d.png'++-- hugo.toml --+disableKinds = ["term", "taxonomy", "home"]+-- layouts/all.html --+All.+-- layouts/page.html --+{{ $pix := .Resources.Get "pix.png" }}+{{ $resized := $pix.Resize "10x10" }}+Resized: {{ $resized.RelPermalink }}+-- content/MyBundle/index.md --+---+title: MyBundle+---+-- pixel.png.txt --+iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==