project config markup.goldmark.renderHooks.image.useEmbedded

Error message

project config markup.goldmark.renderHooks.image.useEmbedded must be one of %s

What it means

Hugo validates `markup.goldmark.renderHooks.image.useEmbedded`, which controls when Hugo's embedded image render hook is used versus a user/theme-provided one. The value must be one of the defined modes (always, auto, fallback, never); anything else aborts config compilation. Legacy boolean `enableDefault` values are converted before this check, so only genuinely unknown strings reach it.

Source

Thrown at config/allconfig/allconfig.go:494

	if c.Markup.Goldmark.RenderHooks.Link.EnableDefault != nil {
		alternative := "Use markup.goldmark.renderHooks.link.useEmbedded instead." + " " + alternativeDetails
		hugo.DeprecateWithLogger("project config key markup.goldmark.renderHooks.link.enableDefault", alternative, "0.148.0", logger.Logger())
		if *c.Markup.Goldmark.RenderHooks.Link.EnableDefault {
			c.Markup.Goldmark.RenderHooks.Link.UseEmbedded = gc.RenderHookUseEmbeddedFallback
		} else {
			c.Markup.Goldmark.RenderHooks.Link.UseEmbedded = gc.RenderHookUseEmbeddedNever
		}
	}

	// Validate render hook configuration.
	renderHookUseEmbeddedModes := []string{
		gc.RenderHookUseEmbeddedAlways,
		gc.RenderHookUseEmbeddedAuto,
		gc.RenderHookUseEmbeddedFallback,
		gc.RenderHookUseEmbeddedNever,
	}
	if !slices.Contains(renderHookUseEmbeddedModes, c.Markup.Goldmark.RenderHooks.Image.UseEmbedded) {
		return fmt.Errorf("project config markup.goldmark.renderHooks.image.useEmbedded must be one of %s", helpers.StringSliceToList(renderHookUseEmbeddedModes, "or"))
	}
	if !slices.Contains(renderHookUseEmbeddedModes, c.Markup.Goldmark.RenderHooks.Link.UseEmbedded) {
		return fmt.Errorf("project config markup.goldmark.renderHooks.link.useEmbedded must be one of %s", helpers.StringSliceToList(renderHookUseEmbeddedModes, "or"))
	}

	c.C = &ConfigCompiled{
		Timeout:             timeout,
		BaseURL:             baseURL,
		BaseURLLiveReload:   baseURL,
		DisabledKinds:       disabledKinds,
		DisabledLanguages:   disabledLangs,
		IgnoredLogs:         ignoredLogIDs,
		KindOutputFormats:   kindOutputFormats,
		DefaultOutputFormat: defaultOutputFormat,
		CreateTitle:         helpers.GetTitleFunc(c.TitleCaseStyle),
		IsUglyURLSection:    isUglyURL,
		IgnoreFile:          ignoreFile,
		MainSections:        c.MainSections,

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Set the value to one of: "always", "auto", "fallback", or "never".
If migrating from `enableDefault = true`, use `useEmbedded = "fallback"` (embedded hook used when no user hook exists).
Check merged config with `hugo config` if the bad value comes from a theme or module.

Example fix

# before
[markup.goldmark.renderHooks.image]
useEmbedded = "true"
# after
[markup.goldmark.renderHooks.image]
useEmbedded = "fallback"

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"auto": true, "always": true, "fallback": true, "never": true}
if v := cfg.Markup.Goldmark.RenderHooks.Image.UseEmbedded; v != "" && !allowed[v] {
    return fmt.Errorf("markup.goldmark.renderHooks.image.useEmbedded %q not in auto|always|fallback|never", v)
}

Prevention

Use only the documented enum values (auto, always, fallback, never), not booleans like true/false
Copy the setting name and value from current Hugo docs — this option changed shape across versions
Validate enum config fields against an allowlist at startup

When it happens

Trigger: Setting `[markup.goldmark.renderHooks.image] useEmbedded = "true"` (string boolean), a typo like "fallbck", or any value outside the allowed set in site, theme, or module config.

Common situations: Migrating from the deprecated `enableDefault` boolean and writing "true"/"false" as strings instead of the new mode names; copying config snippets from outdated blog posts.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/f0bfe53d33895775.json. Report an issue: GitHub ↗.