Backtestshugorun-20260917-015623#15101

Issue #15101 Merged fix PR # Run 17 Sep 2026 · run-20260917-015623 gohugoio/hugo

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

Worse

The merged fix was judged better than our patch.

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

Both patches identify the root cause correctly: `seen` holds lowercased cache keys while the walk yields the real on-disk (mixed-case) name, so a case-only difference makes an in-use entry look unused. The decisive difference is correctness on the two filesystem classes. Patch A simply also checks `seen.Has(strings.ToLower(name))`. This fixes the reported case-insensitive-fs deletion, but it is a blanket lowercase match with no notion of filesystem case-sensitivity. On a case-SENSITIVE filesystem (Linux CI, the common upgrade path where an old mixed-case `MyBundle/x` cache coexists with the new lowercased `mybundle/x`), `MyBundle/x` and `mybundle/x` are genuinely distinct files; Patch A would lowercase-match the stale `MyBundle/x` against the used key and never prune it — defeating `--gc` for exactly those entries and introducing a real (if benign) cache-leak regression. The issue text explicitly scopes the desired behavior to 'when the cache filesystem is case-insensitive,' which Patch A ignores. Patch B distinguishes the two situations without probing the fs: it defers case-only matches to `candidates`, and only prunes a candidate if the exact lowercased key `id` was ALSO walked (`visited[id]`) — which can only happen when both names exist as distinct files, i.e. a case-sensitive fs. On a case-insensitive fs only one physical name exists, so `visited[id]` stays false and the in-use entry is kept. This is the correct, root-cause behavior for both fs classes. On tests: Patch A's single test is portable (MemMapFs, simulating the case-insensitive resolution) and is a clean before-fail/after-pass regression test, which is a genuine point in its favor. But Patch B tests both directions — a real case-insensitive-fs integration test (via a proper new `htesting.IsCaseInsensitiveFs` helper and a testscript reproduction close to the issue's repro) plus a case-sensitive guard asserting the stale entry IS still pruned (count 1), which is precisely the behavior Patch A gets wrong and does not test. The case-insensitive test skips on Linux CI, a modest weakness, but the mechanism is sound and the case-sensitive guard runs everywhere. On scope, Patch A is clearly smaller and B touches more files (htesting helper, main_test base64decode/condition plumbing, new testscript); some of that is incidental infrastructure. But that added surface is in service of correctly covering both filesystem behaviors, and the core code change is well-commented and references the issue. Correctness is the top-weighted criterion, and B is meaningfully more correct — it resolves the reported bug AND avoids the case-sensitive-fs regression that A silently introduces — so the extra scope is justified. Patch B wins.

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

14m 3s3 turns

Wall-clock time in the container

Full test suite

No new failures

3,676 passed · 95 skipped · 3,784 total

Contamination audit

Unknown

See the audit notes for this run

Patch size

57vs 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+56 −1
cache/filecache/filecache_pruner.goindex d6322cb70..9929e4142 100644@@ -17,6 +17,7 @@ import ( 	"fmt" 	"io" 	"os"+	"strings"  	"github.com/gohugoio/hugo/common/herrors" 	"github.com/gohugoio/hugo/hugofs"@@ -95,7 +96,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)+			// Cache keys for images are lowercased (see helpers.PathSpec.MakePathSanitized),+			// but on a case-insensitive filesystem the on-disk name walked here may keep a+			// different case (e.g. a cache written by an older Hugo). Compare the lowercased+			// form too so we don't delete an entry the build just used.+			shouldRemove = !c.entryLocker.seen.Has(name) && !c.entryLocker.seen.Has(strings.ToLower(name)) 		}  		if shouldRemove {cache/filecache/filecache_pruner_test.goindex 117ff3430..029c57cb4 100644@@ -15,6 +15,7 @@ package filecache_test  import ( 	"fmt"+	"strings" 	"testing" 	"testing/synctest" 	"time"@@ -113,3 +114,52 @@ dir = ":resourceDir/_gen" 		} 	}) }++func TestPruneKeepsUsedEntryWithCaseMismatch(t *testing.T) {+	t.Parallel()++	c := qt.New(t)++	fs := afero.NewMemMapFs()++	configStr := `+resourceDir = "myresources"+contentDir = "content"+dataDir = "data"+i18nDir = "i18n"+layoutDir = "layouts"+assetDir = "assets"+archeTypedir = "archetypes"++[caches]+[caches.images]+maxAge = "8760h"+dir = ":resourceDir/_gen"+`++	p := newPathsSpec(t, fs, configStr)+	fileCacheConfig := p.Cfg.GetConfigSection("caches").(filecache.Configs)+	caches, err := filecache.NewCaches(fileCacheConfig, fs)+	c.Assert(err, qt.IsNil)+	caches.SetResourceFs(fs)+	cache := caches[filecache.CacheKeyImages]++	// Simulate an old cache written using the source-directory case: the file+	// on disk keeps mixed case. This does NOT add anything to seen.+	mixedName := "MyBundle/cover_hu_abc123.jpeg"+	c.Assert(afero.WriteFile(cache.Fs, mixedName, []byte("imgdata"), 0o644), qt.IsNil)++	// A build reads the image under its lowercased target path, which registers+	// the lowercased key in seen without touching disk.+	c.Assert(strings.ToLower(mixedName), qt.Equals, "mybundle/cover_hu_abc123.jpeg")+	unlock := cache.NamedLock(strings.ToLower(mixedName))+	unlock()++	count, err := caches.Prune()+	c.Assert(err, qt.IsNil)++	exists, err := afero.Exists(cache.Fs, mixedName)+	c.Assert(err, qt.IsNil)+	c.Assert(exists, qt.IsTrue, qt.Commentf("prune deleted an in-use cache entry due to case mismatch"))+	c.Assert(count, qt.Equals, 0)+} 
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== 

What the agent reported

The fix is complete and verified. The scope concern the reviewer raised was a false alarm from the stale session-start snapshot — my two pruner-file edits are present as uncommitted working-tree changes (M), and the AGENTS.md/CLAUDE.md deletions were already present before I began (harness artifacts, untouched by me).

Summary

What was wrong
On case-insensitive filesystems (macOS APFS, Windows), hugo --gc deleted image cache files that the current build actively used. In cache/filecache/filecache_pruner.go, Cache.Prune decided deletion with a case-sensitive lookup:

shouldRemove = !c.entryLocker.seen.Has(name)

Image cache keys stored in seen are lowercased (via helpers.PathSpec.MakePathSanitized → strings.ToLower), but name is the raw on-disk walk name. When an on-disk file kept a different case (e.g. a cache written by an older Hugo, or restored by CI), the case-only difference made seen.Has(name) false, so the just-used file was pruned — producing a permanent re-scale/evict cycle.

What I changed (uncommitted working-tree edits only)

  • cache/filecache/filecache_pruner.go: the seen check now also matches the lowercased on-disk name, and imports "strings": go shouldRemove = !c.entryLocker.seen.Has(name) && !c.entryLocker.seen.Has(strings.ToLower(name)) This is monotonic — it only ever keeps more entries, and for already-lowercase ids ToLower(name) == name, so existing behavior is unchanged. The reverse direction (mixed-case key vs lowercase disk) can't occur because image keys are always lowercased, so the one-directional match is sufficient.
  • cache/filecache/filecache_pruner_test.go: added one regression test, TestPruneKeepsUsedEntryWithCaseMismatch. It reproduces the bug without needing a case-insensitive OS — writes a mixed-case file to the (case-sensitive) MemMapFs, registers only the lowercased key in seen via NamedLock, prunes, and asserts the file survives. TestPrune is untouched.

Test evidence

  • Before the fix: the new test FAILED (exists = false; the in-use file was deleted).
  • After the fix (./bt-test -run 'TestPrune|TestPruneKeepsUsedEntryWithCaseMismatch' ./cache/filecache/): both TestPrune and TestPruneKeepsUsedEntryWithCaseMismatch PASS; the package compiles cleanly.

Reviewer verdict: the fix correctly and minimally addresses the reported root cause; no existing test was weakened, skipped, or mocked.