Backtestshugorun-20261009-153657#15234

Issue #15234 Merged fix PR #15252 Run 9 Oct 2026 · run-20261009-153657 gohugoio/hugo

templates.Defer: identical block bodies in different output formats share one escaping mode, chosen non-deterministically per build

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 same way. In `handleWith` they fold the owner's `IsPlainText` flag into the deferred-template hash. This means an HTML template and a plain-text template with identical block bodies no longer collide on one `deferredID`. That collision is what let `addDeferredTemplate` keep whichever registration came first in randomized map order. Both keep sharing within one escaping mode, which preserves the documented same-format key/body cache behaviour. A tags the input with a single byte (`h`/`t`); B uses a `%t:` prefix. These are equivalent in effect.

The difference is mainly in tests. B adds one integration test that builds once. Because the bug depends on map iteration order, a single build would fail before the fix only some of the time, so it is a weak regression guard. A's defer test runs 10 builds per configuration. It covers both the same-key case and the different-key control (`KH`/`KT`) from the issue, and it uses exact content assertions. That reliably catches the nondeterminism. A also adds a test that pins the constraint the issue stresses: two layouts of the same output format with identical bodies and the same key still share one execution (`EXEC[1]` on both pages). This guards against an over-broad fix such as hashing the template name.

A also extends into `handleWithPartial`. It adds the plain-text flag to the hash, which is redundant because the owner name is already hashed. It also sets `IsPlainText` on the inner decorator template, and adds a test for decorator escaping. This is beyond the issue's ask and carries some risk: the descriptor is mutated after insertion. It is, however, backed by its own test.

On the core fix the two are equal. A's substantially stronger, determinism-aware tests and its explicit coverage of the same-format sharing constraint make it the better patch.

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

1h 15m

Wall-clock time in the container

Full test suite

No new failures

902 passed · 28 skipped · 930 total

Contamination audit

Clean

No sign the agent saw the real fix

Patch size

106vs 29 merged

Changed lines, ours vs merged

What version of Hugo are you using (hugo version)?

<pre>
$ hugo version
hugo v0.164.0-ce2470e7012b5ab5fc4e10ebe4027e9f8d9e00dc+extended windows/amd64 BuildDate=2026-07-06T16:39:30Z VendorInfo=gohugoio
</pre>

Does this issue reproduce with the latest release?

Yes.

hugo v0.165.0-76a5e1880ab46688155b02e99bab9be2a6134492+extended windows/amd64 BuildDate=2026-08-12T14:26:28Z VendorInfo=gohugoio

Over one run of 40 consecutive builds of the unchanged reproduction site below with that binary, 28 builds published the wrong value in public/index.html and 12 published the wrong value in public/index.txt. All 40 exited 0, and none printed a warning or an error.

Summary

When two templates belonging to different output formats contain byte-identical templates.Defer block bodies, both blocks do execute, each with its own correct output-format context. What they share is the escaping applied inside the block, and which of the two escaping modes survives changes from build to build of an unchanged site. On every build exactly one of the two outputs is therefore wrong: either an HTML page publishes a value raw that it escapes correctly a few characters earlier outside the block, or a plain-text page receives HTML entities.

Reproduction

Three files in an empty directory. No content, no modules, no external tooling.

hugo.toml:

baseURL = 'https://example.org/'
title = 'defer probe'
disableKinds = ['page', 'section', 'taxonomy', 'term', 'RSS', 'sitemap', 'robotsTXT']

[outputFormats.probe]
mediaType = 'text/plain'
baseName = 'index'
isPlainText = true

[outputs]
home = ['html', 'probe']

layouts/home.html:

{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "K" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}

layouts/home.probe.txt, byte-identical to layouts/home.html (both md5 c921197a9c8637852e38d94a0352359d):

{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "K" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}

OUT[...] interpolates the value outside the deferred block, IN[...] interpolates the same value inside it. Then run hugo several times without changing anything, and look at public/index.html and public/index.txt after each run.

What happens

Two consecutive runs of the same command on the unchanged site, pasted verbatim:

$ hugo --logLevel info
Start building sites …
hugo v0.164.0-ce2470e7012b5ab5fc4e10ebe4027e9f8d9e00dc+extended windows/amd64 BuildDate=2026-07-06T16:39:30Z VendorInfo=gohugoio

INFO  build:  step process substep collect files 0 files_total 0 pagesources_total 0 resourcesources_total 0 duration 0s
INFO  build:  step process duration 0s
INFO  build:  step assemble duration 0s
INFO  build:  step render substep pages site en outputFormat html duration 1.3703ms
INFO  build:  step render substep pages site en outputFormat probe duration 509.5µs
INFO  build:  step render pages 2 content 0 duration 1.8798ms
INFO  build:  step render deferred count 2 duration 1.7766ms
INFO  build:  step postProcess duration 0s
INFO  build:  duration 4.171ms

                  │ EN
──────────────────┼────
 Pages            │  2
 Paginator pages  │  0
 Non-page files   │  0
 Static files     │  0
 Processed images │  0
 Aliases          │  0
 Cleaned          │  0

Total in 12 ms
--- public/index.html ---
OUT[&lt;b&gt;&amp;]IN[<b>&]
--- public/index.txt ---
OUT[<b>&]IN[<b>&]
$ hugo --logLevel info
Start building sites …
hugo v0.164.0-ce2470e7012b5ab5fc4e10ebe4027e9f8d9e00dc+extended windows/amd64 BuildDate=2026-07-06T16:39:30Z VendorInfo=gohugoio

INFO  build:  step process substep collect files 0 files_total 0 pagesources_total 0 resourcesources_total 0 duration 513.8µs
INFO  build:  step process duration 513.8µs
INFO  build:  step assemble duration 0s
INFO  build:  step render substep pages site en outputFormat html duration 517.9µs
INFO  build:  step render substep pages site en outputFormat probe duration 517.2µs
INFO  build:  step render pages 2 content 0 duration 1.0351ms
INFO  build:  step render deferred count 2 duration 2.0736ms
INFO  build:  step postProcess duration 0s
INFO  build:  duration 3.6225ms

                  │ EN
──────────────────┼────
 Pages            │  2
 Paginator pages  │  0
 Non-page files   │  0
 Static files     │  0
 Processed images │  0
 Aliases          │  0
 Cleaned          │  0

Total in 12 ms
--- public/index.html ---
OUT[&lt;b&gt;&amp;]IN[&lt;b&gt;&amp;]
--- public/index.txt ---
OUT[<b>&]IN[&lt;b&gt;&amp;]

In the first run the HTML page publishes <b>& raw inside the block, a few characters after escaping the same value correctly outside it. In the second run the plain-text page receives &lt;b&gt;&amp;. Nothing changed between the two runs.

Quantified over builds of the unchanged site, each build a separate one-shot hugo invocation:

Hugo versionbuildsindex.html published raw <b>& inside the blockindex.txt published &lt;b&gt;&amp; inside the block
v0.164.0, fresh copy of the site per build402515
v0.164.0, fresh copy of the site per build, second run402317
v0.165.0, fresh copy of the site per build402614
v0.165.0, fresh copy of the site per build, second run402812
v0.164.0, repeated builds in one directory1284
v0.165.0, repeated builds in one directory853

In all 180 of those builds the two output formats carried the same string inside the block, so exactly one of the two published files was wrong every time; outside the block the value was escaped correctly for its format in every build.

What I expected

Each format's deferred block rendered under that format's own escaping — IN[&lt;b&gt;&amp;] in public/index.html and IN[<b>&] in public/index.txt — and the same result on every build of an unchanged site.

The documentation says "The output format, site, and language will be the same, even if the execution is deferred." The output-format context does hold up, as the identity-token control below shows; it is the escaping regime that does not follow the output format.

Controls

All of these were run at both v0.164.0 and v0.165.0.

The block really does execute once per output format. Adding {{ warnf "DEFER-EXEC-%d" math.Counter }} to the start of the still byte-identical block body logs two executions in every build:

WARN  DEFER-EXEC-1
WARN  DEFER-EXEC-2
INFO  build:  step render deferred count 2 duration 1.7497ms
--- public/index.html ---
OUT[&lt;b&gt;&amp;]IN[<b>&]
--- public/index.txt ---
OUT[<b>&]IN[<b>&]

So this is not one rendering substituted into two files; it is two renderings sharing one escaping mode.

Different key values do not separate them. With "KH" in layouts/home.html and "KT" in layouts/home.probe.txt, the block bodies still byte-identical, the escaping stayed shared and kept flipping: 36 builds, 22 with the HTML page wrong and 14 with the plain-text page wrong.

Different block body text does separate them, stably. Changing the body to INH[{{ .v }}] in the HTML template and INT[{{ .v }}] in the plain-text template gives the correct per-format result in 36 of 36 builds, with no flip: INH[&lt;b&gt;&amp;] in public/index.html and INT[<b>&] in public/index.txt.

The per-format context inside the block is correct. With the body still byte-identical in both templates, but carrying an output-format identity token next to the value:

{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "K" "data" (dict "v" $v))) }}IN[{{ (index page.AlternativeOutputFormats 0).Name }}|{{ .v }}]{{ end }}

With exactly two formats configured the single alternative names the other one, so IN[probe|...] marks the execution that produced the HTML page and IN[html|...] the one that produced the plain-text page. That token was correct in 36 of 36 builds, while the escaping of the value beside it in the very same body was shared and flipped across those builds:

public/index.html   OUT[&lt;b&gt;&amp;]IN[probe|<b>&]
public/index.txt    OUT[<b>&]IN[html|<b>&]

public/index.html   OUT[&lt;b&gt;&amp;]IN[probe|&lt;b&gt;&amp;]
public/index.txt    OUT[<b>&]IN[html|&lt;b&gt;&amp;]

Where this appears to come from

Offered as a lead from reading the source, not as an instrumented finding.

tpl/tplimpl/templatetransform.go, handleWith (v0.164.0, function at line 409) registers the extracted block under a hash of the block body alone, at lines 450-459:

inner := withNode.List.CopyList()
s := inner.String()
...
innerHash := hashing.XxHashFromStringHexEncoded(s)
deferredID := tpl.HugoDeferredTemplatePrefix + innerHash
...
c.deferNodes[deferredID] = inner

Nothing about the owning template, its output format or its media type enters that identifier, so two templates in different output formats with the same body produce the same deferredID.

tpl/tplimpl/templatestore.go, addDeferredTemplate (v0.164.0, function at line 916) then keeps only the first registration under that name, and the first owner fixes the parse namespace for whoever comes later:

if _, found := t.templatesByPath.Get(name); found {
    return nil
}
...
if owner.D.IsPlainText {
    prototype := t.tns.parseText
    ...
} else {
    prototype := t.tns.parseHTML
    ...
}

That is exactly the escaping regime the two output formats disagree about, and the loser silently inherits the winner's.

Which owner gets there first looks order-dependent. transformTemplates (function at line 1916) reaches the registrations by ranging s.templates() at line 1937, and that iterator's inner loop at line 1784 ranges a map[nodeKey]*TemplInfo — the value type of treeMain, declared at line 447 — whose iteration order Go randomizes per run. I found no sort on that path.

One contrast worth noting: the sibling transform in the same file, handleWithPartial (function at line 324), hashes the owning template's name into its identifier at line 335 — hashing.XxHashFromStringHexEncoded(c.t.Name() + withNodeInnerString) — while the older defer path does not.

I checked the implicated files at v0.164.0, v0.165.0 and master 7b5199fdeff7d7682e9f979f468d55bc7b67b934: tpl/tplimpl/templatestore.go, tpl/templates/templates.go and tpl/template.go are byte-identical at all three, and tpl/tplimpl/templatetransform.go differs at master only outside this path — the handleWith lines quoted above are unchanged there, at 405-414.

A constraint on any fix

Hashing the owning template's name into the deferred identifier, the way handleWithPartial does, would break something the documentation promises for key: "This will, combined with a hash of the template content, be used as a cache key." Two different layouts of the same output format with identical bodies and one shared key share a single execution today, and that is worth keeping — at both versions, on a variant of the site above reduced to one output format and with the page kind enabled plus one content file, so that single.html renders at all, I measured a single DEFER-EXEC-1 for a home.html and a single.html written that way, with both pages publishing the shared result.

Separating registrations by the property that actually differs here — the owner's IsPlainText, or its output format — would fix the escaping while leaving that documented same-format sharing untouched.

Related, not duplicates

  • #7774, fixed by #8462 ("Fixes #7774", merged 2021-04-23): per-build nondeterminism in output-format template lookup for shortcodes. Same failure shape, different subsystem, and it predates templates.Defer.
  • #13236: two empty deferred blocks in the same template collided on the identifier __hdeferred/cafc7706cee4572b and panicked; closed as completed. That is the same body-only identifier, in a different situation — the collision there is inside one template, and the cross-output-format escaping consequence does not come up.

I did not find an existing report covering byte-identical templates.Defer bodies across output formats.

What I did not establish

  • Which registration wins in any individual build. I inferred the winner from the escaping in the published output; I did not instrument the running binary to observe the registration.
  • Platform generality. Everything above was measured on one machine, Windows 11, amd64 extended builds. Whether the split differs on another platform or core count is unmeasured.
  • Two non-plain-text formats sharing a body. The escaping observable needs an isPlainText format paired with an HTML one, so two HTML-ish formats sharing a body were not tested and the reach across format combinations is unknown.

The two patches

Our patch+104 −2
tpl/templates/decorator_integration_test.goindex e671c446c..42cb74cc8 100644@@ -499,3 +499,34 @@ Content-Security-Policy: script-src 'self'{{ range $k, $v := $hashes }} '{{ $k } 	b.AssertFileContentExact("public/index.html", "<script>\nconsole.log(\"Hello world\");\n</script>") 	b.AssertFileContentExact("public/_headers", "Content-Security-Policy: script-src 'self' 'sha256-t6z9j4/CagmaDDbn6nHbntzt8PRk8HZ1TwrgdYuZjbE=' 'sha256-wVbS8f78ttoSSGU80KghGoPcTO8DXqT0Uc/87a7zMdk=';") }++// The inner block of a partial decorator must be escaped according to the+// output format of the template it lives in.+func TestDecoratorInnerPlainTextAndHTML(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+baseURL = 'https://example.org/'+disableKinds = ['page', 'section', 'taxonomy', 'term', 'RSS', 'sitemap', 'robotsTXT']+[outputFormats.probe]+mediaType = 'text/plain'+baseName = 'index'+isPlainText = true+[outputs]+home = ['html', 'probe']+-- layouts/_partials/wrap.html --+W[{{ inner . }}]+-- layouts/_partials/wrap.probe.txt --+W[{{ inner . }}]+-- layouts/home.html --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with partial "wrap.html" $v }}IN[{{ . }}]{{ end }}+-- layouts/home.probe.txt --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with partial "wrap.probe.txt" $v }}IN[{{ . }}]{{ end }}+`++	b := hugolib.Test(t, files)++	b.AssertFileContentExact("public/index.html", "OUT[&lt;b&gt;&amp;]W[IN[&lt;b&gt;&amp;]]")+	b.AssertFileContentExact("public/index.txt", "OUT[<b>&]W[IN[<b>&]]")+}tpl/templates/defer_integration_test.goindex 4f67898bc..c7212c5c3 100644@@ -367,3 +367,61 @@ Home. 	b.Assert(err, qt.Not(qt.IsNil)) 	b.Assert(err.Error(), qt.Contains, "templates.Defer cannot be used inside a partialCached partial") }++// Identical deferred block bodies in a plain text and an HTML output format+// must each be executed with their own escaping.+func TestDeferIdenticalBodiesPlainTextAndHTML(t *testing.T) {+	t.Parallel()++	for _, keys := range [][2]string{{"K", "K"}, {"KH", "KT"}} {+		files := `+-- hugo.toml --+baseURL = 'https://example.org/'+disableKinds = ['page', 'section', 'taxonomy', 'term', 'RSS', 'sitemap', 'robotsTXT']+[outputFormats.probe]+mediaType = 'text/plain'+baseName = 'index'+isPlainText = true+[outputs]+home = ['html', 'probe']+-- layouts/home.html --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "KEYH" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}+-- layouts/home.probe.txt --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "KEYT" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}+`+		files = strings.ReplaceAll(files, "KEYH", keys[0])+		files = strings.ReplaceAll(files, "KEYT", keys[1])++		// The registration order used to depend on map iteration order,+		// so build a few times.+		for range 10 {+			b := hugolib.Test(t, files)+			b.AssertFileContentExact("public/index.html", "OUT[&lt;b&gt;&amp;]IN[&lt;b&gt;&amp;]")+			b.AssertFileContentExact("public/index.txt", "OUT[<b>&]IN[<b>&]")+		}+	}+}++// Identical deferred block bodies with the same key in different templates of+// the same output format share one execution.+func TestDeferIdenticalBodiesSameOutputFormatShareExecution(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+baseURL = 'https://example.org/'+disableKinds = ['section', 'taxonomy', 'term', 'RSS', 'sitemap', 'robotsTXT']+-- content/p1.md --+---+title: p1+---+-- layouts/home.html --+{{ with (templates.Defer (dict "key" "K")) }}EXEC[{{ math.Counter }}]{{ end }}+-- layouts/single.html --+{{ with (templates.Defer (dict "key" "K")) }}EXEC[{{ math.Counter }}]{{ end }}+`++	b := hugolib.Test(t, files)+	b.AssertFileContentExact("public/index.html", "EXEC[1]")+	b.AssertFileContentExact("public/p1/index.html", "EXEC[1]")+}tpl/tplimpl/templatetransform.goindex ab42412eb..bb1060de1 100644@@ -287,7 +287,9 @@ func (c *templateTransformContext) handleWithPartial(withNode *parse.WithNode) { 	if c.hasBreakOrContinueOutsideRange(withNode.List) { 		return 	}-	innerHash := hashing.XxHashFromStringHexEncoded(c.t.Name() + withNodeInnerString)+	// Include the owner's plain text flag, as the inner block is parsed and+	// escaped like its owner (see below).+	innerHash := hashing.XxHashFromStringHexEncoded(fmt.Sprintf("%t|%s%s", c.t.D.IsPlainText, c.t.Name(), withNodeInnerString)) 	internalPartialName := fmt.Sprintf("_partials/%s%s", PartialDecoratorPrefix, innerHash)  	if c.lookupFn(internalPartialName, c.t) == nil {@@ -301,6 +303,8 @@ func (c *templateTransformContext) handleWithPartial(withNode *parse.WithNode) { 			c.err = fmt.Errorf("failed to find internal partial decorator template %q after insertion", internalPartialName) 			return 		}+		// The inner block must be parsed and escaped like its owner.+		ti.D.IsPlainText = c.t.D.IsPlainText  		cc := newTemplateTransformContext(ti, c.store, c.lookupFn) @@ -408,7 +412,16 @@ func (c *templateTransformContext) handleWith(withNode *parse.WithNode) { 		c.err = errors.New("resources.PostProcess cannot be used in a deferred template") 		return 	}-	innerHash := hashing.XxHashFromStringHexEncoded(s)+	// The deferred template is parsed in either the text or the HTML namespace+	// depending on the owner, so identical bodies in plain text and HTML+	// templates must not share an ID. Templates of the same kind with+	// identical bodies (and key) still share the execution.+	// The one-byte kind tag keeps the hash input unambiguous.+	kind := "h"+	if c.t.D.IsPlainText {+		kind = "t"+	}+	innerHash := hashing.XxHashFromStringHexEncoded(kind + s) 	deferredID := tpl.HugoDeferredTemplatePrefix + innerHash  	c.deferNodes[deferredID] = inner 
Merged fix · PR #15252+28 −1
tpl/templates/defer_integration_test.goindex 4f67898bc..46c126ac1 100644@@ -323,6 +323,30 @@ End. 	b.AssertFileContent("public/index.html", "Home.", "Defer 1", "Defer 2", "Defer 3", "End.") } +// See issue 15234.+func TestDeferDifferentOutputFormats(t *testing.T) {+	t.Parallel()++	files := `+-- hugo.toml --+[outputFormats.probe]+mediaType = "text/plain"+baseName = "index"+isPlainText = true+[outputs]+home = ["html", "probe"]+-- layouts/home.html --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "K" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}+-- layouts/home.probe.txt --+{{ $v := "<b>&" }}OUT[{{ $v }}]{{ with (templates.Defer (dict "key" "K" "data" (dict "v" $v))) }}IN[{{ .v }}]{{ end }}+`++	b := hugolib.Test(t, files)++	b.AssertFileContent("public/index.html", "OUT[&lt;b&gt;&amp;]IN[&lt;b&gt;&amp;]")+	b.AssertFileContent("public/index.txt", "OUT[<b>&]IN[<b>&]")+}+ // See issue 13492. func TestDeferInsidePartialCachedShouldFail(t *testing.T) { 	t.Parallel()tpl/tplimpl/templatetransform.goindex ab42412eb..dcb59abe7 100644@@ -408,7 +408,10 @@ func (c *templateTransformContext) handleWith(withNode *parse.WithNode) { 		c.err = errors.New("resources.PostProcess cannot be used in a deferred template") 		return 	}-	innerHash := hashing.XxHashFromStringHexEncoded(s)+	// The deferred template is parsed using the owner's escaping mode. Keep+	// identical bodies shared within that mode, but don't let HTML and plain+	// text templates register the same deferred template.+	innerHash := hashing.XxHashFromStringHexEncoded(fmt.Sprintf("%t:%s", c.t.D.IsPlainText, s)) 	deferredID := tpl.HugoDeferredTemplatePrefix + innerHash  	c.deferNodes[deferredID] = inner