project config markup.goldmark.renderHooks.link.useEmbedded

Error message

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

What it means

Identical validation to error 67 but for the link render hook: `markup.goldmark.renderHooks.link.useEmbedded` chooses when Hugo's embedded link render hook applies and must be one of the defined modes (always, auto, fallback, never). Invalid values fail config compilation immediately.

Source

Thrown at config/allconfig/allconfig.go:497

		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,
		Clock:               clock,
		HTTPCache:           httpCache,
		transientErr:        transientErr,

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Use one of "always", "auto", "fallback", or "never".
For old `enableDefault = true` behavior, use `useEmbedded = "fallback"`.
Inspect `hugo config` output to find which config file supplies the invalid value.

Example fix

# before
[markup.goldmark.renderHooks.link]
useEmbedded = "yes"
# after
[markup.goldmark.renderHooks.link]
useEmbedded = "auto"

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.Link.UseEmbedded; v != "" && !allowed[v] {
    return fmt.Errorf("markup.goldmark.renderHooks.link.useEmbedded %q not in auto|always|fallback|never", v)
}

Prevention

Same enum as the image hook: auto, always, fallback, never — don't set booleans
Keep image and link hook settings consistent and validated together
Fail fast in your own config layer instead of letting Hugo's load reject it later

When it happens

Trigger: Setting `[markup.goldmark.renderHooks.link] useEmbedded` to a string outside the allowed set — a typo, a string boolean, or a stale value from old documentation.

Common situations: Same migration pitfall as the image hook: converting the deprecated `enableDefault` boolean into string "true"/"false" instead of a mode name; theme configs written for older Hugo versions.

Related errors

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