Repository navigation
Description
This issue report was written by Claude Opus 5.5, and checked against Hugo v0.168.0.
What version of Hugo are you using (hugo version)?
$ hugo version hugo v0.168.0-e27a6760c5547237f87d353aebe0580feadb20f4+extended linux/amd64 BuildDate=2026-10-13T16:42:50Z VendorInfo=gohugoio
Does this issue reproduce with the latest release?
Yes. It also reproduces with v0.167.0, and the code involved is unchanged on master (77230eb).
Description
When the image passed to images.Overlay (or images.Mask) was itself processed, the filtered image's file name depends on whether that processed image was created in this build or read from the file cache. With an empty resource cache, build 1 publishes the overlay under one name and build 2 under another. The bytes are identical. From build 2 onwards the name stays the same.
Expected: the same name in every build.
Actual: one name in the first build after the overlaid image is (re)processed, and a different name in later builds.
Reproduction
#!/usr/bin/env bash
# Usage: ./repro.sh [extra hugo flags, e.g. --gc]
set -euo pipefail
cd "$(mktemp -d)"
mkdir -p assets layouts
# 64x64 solid-colour PNG
echo 'iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAATklEQVR42u3PQQkAAAgEsIt20Y1mBN/CYAWWaV+LgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgMBlAXfcAS0jwTZyAAAAAElFTkSuQmCC' | base64 -d > assets/a.png
echo "disableKinds = ['page', 'rss', 'section', 'sitemap', 'taxonomy', 'term']" > hugo.toml
cat > layouts/home.html <<'HTML'
{{- $a := resources.Get "a.png" -}}
{{- $s := $a.Process "resize 32x" -}}
overlay={{ ($a | images.Filter (images.Overlay $s 0 0)).RelPermalink }} key={{ $s.Key }}
HTML
for i in 1 2 3; do
${HUGO:-hugo} --quiet "$@"
echo "build $i: $(cat public/index.html)"
echo " resources/_gen/images: $(ls resources/_gen/images | tr '\n' ' ')"
done
(cd public && md5sum a_hu_*.png)Output with v0.168.0:
$ ./repro.sh
build 1: overlay=/a_hu_41f8c20fc0cc13b7.png key=/a_hu_498f860d9a6e2307.png_2100844135326038661
resources/_gen/images: a_hu_41f8c20fc0cc13b7.png a_hu_498f860d9a6e2307.png
build 2: overlay=/a_hu_2068adca79b7981a.png key=/a_hu_498f860d9a6e2307.png
resources/_gen/images: a_hu_2068adca79b7981a.png a_hu_41f8c20fc0cc13b7.png a_hu_498f860d9a6e2307.png
build 3: overlay=/a_hu_2068adca79b7981a.png key=/a_hu_498f860d9a6e2307.png
resources/_gen/images: a_hu_2068adca79b7981a.png a_hu_41f8c20fc0cc13b7.png a_hu_498f860d9a6e2307.png
afcf7e427a895667f311c7877366ee4a a_hu_2068adca79b7981a.png
afcf7e427a895667f311c7877366ee4a a_hu_41f8c20fc0cc13b7.png
$ ./repro.sh --gc
build 1: overlay=/a_hu_41f8c20fc0cc13b7.png key=/a_hu_498f860d9a6e2307.png_2100844135326038661
resources/_gen/images: a_hu_41f8c20fc0cc13b7.png a_hu_498f860d9a6e2307.png
build 2: overlay=/a_hu_2068adca79b7981a.png key=/a_hu_498f860d9a6e2307.png
resources/_gen/images: a_hu_2068adca79b7981a.png a_hu_498f860d9a6e2307.png
build 3: overlay=/a_hu_2068adca79b7981a.png key=/a_hu_498f860d9a6e2307.png
resources/_gen/images: a_hu_2068adca79b7981a.png a_hu_498f860d9a6e2307.png
afcf7e427a895667f311c7877366ee4a a_hu_2068adca79b7981a.png
afcf7e427a895667f311c7877366ee4a a_hu_41f8c20fc0cc13b7.png
$s.Key has a _<hash> suffix in build 1 and none in build 2. Both overlay files in public/ have the same MD5. Replacing images.Overlay $s 0 0 with images.Mask $s gives the same pattern: two names, identical bytes.
Cause
- On a file cache hit,
ImageCache.getOrCreatemarks the image withsetSourceFilenameIsHash(true). Thecreatepath just below it does not:
Line 67 in 77230eb
img.setSourceFilenameIsHash(true) genericResource.Key()appends_<hash>only when!l.sourceFilenameIsHash(includeHashInKeyis always true for images, resource_spec.go#L204):
Line 465 in 77230eb
if l.includeHashInKey && !l.sourceFilenameIsHash { OverlayandMaskput the other image'sKey()into the filter options, and the filter options feed into the output name:
hugo/resources/images/filters.go
Line 51 in 77230eb
Options: newFilterOpts(src.Key(), x, y),
hugo/resources/images/filters.go
Line 59 in 77230eb
Options: newFilterOpts(mask.Key()),
Impact
- The overlay is processed a second time in build 2, under its new name.
- With
--gc, build 2 deletes the build-1 file, so the cache only settles on the second build after a processed overlay source changes. - The published URL depends on the state of the resource cache. Two builds of the same commit, one with a warm cache and one with a cold cache, publish the same bytes under different URLs. That causes needless uploads on deploy and churns CDN caches.
Possible fix
Making the key of a processed image the same whether it was created in this build or read from the cache would fix this, for example by setting the flag in both paths, or by having Overlay/Mask use a key that does not depend on where the image came from. Note that sourceFilenameIsHash also affects Publish() (resource.go#L513), so the first option may have other effects. I have not tested either option.
Related: #8066 (which image's name an overlay's output takes; it does not cover this instability) and #11856 (a processed image's name differing after a cache read, now closed).
Activity
resources: Make processed image key stable across builds
github-actions commentedon Nov 12, 2026
This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.