Skip to content

images.Overlay and images.Mask output name changes depending on whether the overlaid image came from the file cacheΒ #15467

Closed

Description

@justinsteven

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

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

  1. self-assigned this
    on Oct 20, 2026
  2. added this to the v0.169.0 milestone on Oct 20, 2026
  3. added a commit that references this issue on Oct 21, 2026
    ff4eab7
  4. github-actions commented on Nov 12, 2026

    @github-actions

    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.

  5. locked as resolved and limited conversation to collaborators on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions