gohugoio/hugo · error

failed to encode file cache entry: %w

Error message

failed to encode file cache entry: %w

What it means

transform.ToMath caches rendered output to Hugo's misc file cache. After computing a result it JSON-encodes a fileCacheEntry (version, output, warnings) into the cache (transform.go:327-332). If json.Encoder.Encode fails — e.g. due to an unencodable value inside the result — the error wraps the encoding failure. Encoding a simple struct should not normally fail.

Source

Thrown at tpl/transform/transform.go:331

			if err != nil {
				return nil, err
			}
			result, err := k.Execute(ctx, message)
			if err != nil {
				return nil, err
			}

			e := fileCacheEntry{
				Version:  fileCacheEntryVersion,
				Output:   result.Data.Output,
				Warnings: result.Header.Warnings,
			}

			buf := &bytes.Buffer{}
			enc := json.NewEncoder(buf)
			enc.SetEscapeHTML(false)
			if err := enc.Encode(e); err != nil {
				return nil, fmt.Errorf("failed to encode file cache entry: %w", err)
			}
			return hugio.NewReadSeekerNoOpCloserFromBytes(buf.Bytes()), nil
		})
		if err != nil {
			return "", err
		}

		var e fileCacheEntry
		if err := json.NewDecoder(r).Decode(&e); err != nil {
			return "", fmt.Errorf("failed to decode file cache entry: %w", err)
		}

		for _, warning := range e.Warnings {
			ns.deps.Log.Warnf("transform.ToMath: %s", warning)
		}

		return template.HTML(e.Output), err
	})

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Clear the Hugo cache (--gc or remove the cache directory) and rebuild.
2. Update Hugo to pick up WASM/KaTeX protocol fixes.
3. If persistent, report as a Hugo bug with the LaTeX input.

// Clear cache and retry; this is almost always a transient/corrupt-cache issue:
// 1. hugo --gc   (or rm -rf $TMPDIR/hugo_cache)
// 2. hugo

When it happens

Trigger: The KaTeX WASM result contains data that cannot be JSON-serialized into the fileCacheEntry struct (e.g. a non-string in Output/Warnings). This is an internal/cache-layer failure during ToMath.

Common situations: Very rare; would indicate a Hugo/WASM protocol regression producing malformed KatexOutput. Could appear if the file cache is on a read-only or full filesystem where the write fails upstream — though that surfaces differently.

Related errors

• failed to decode file cache entry: %w
• must provide at least one argument
• failed to create internal partial decorator template %q: %w
• failed to add internal partial decorator template %q: %w
• failed to transform internal partial decorator template %q:

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/6e17c7cc2d3e7a82. Report an issue: GitHub.