project config markup.goldmark.renderHooks.link.useEmbedded…

Error message

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

What it means

Returned by CompileConfig when markup.goldmark.renderHooks.link.useEmbedded is not one of the four allowed modes: always, auto, fallback, never. Same validation shape as the image hook (error 257) but for link render hooks.

Solutions

Set the value to one of: always, auto, fallback, never.
If migrating from enableDefault: true → fallback, false → never.
Remove the key to accept the default.

Example fix

// before
[markup.goldmark.renderHooks.link]
useEmbedded = "true"
// after
[markup.goldmark.renderHooks.link]
useEmbedded = "fallback"

Defensive patterns

Strategy: validation

Validate before calling

var useEmbeddedModes = []string{"always","auto","fallback","never"}
func validateLinkUseEmbedded(s string) error {
  if !slices.Contains(useEmbeddedModes, s) { return fmt.Errorf("useEmbedded must be one of %v", useEmbeddedModes) }
  return nil
}

Prevention

Apply the same migration rule as image: true→fallback, false→never.
Avoid locale-translated mode strings.
Omit the key to default.

When it happens

Trigger: Setting `markup.goldmark.renderHooks.link.useEmbedded` to any value outside {always, auto, fallback, never}, e.g. 'yes', 'on', '1', 'default'.

Common situations: Same migration pain as 257: older configs used the boolean enableDefault; mistyped or locale-translated strings ('jamais' instead of 'never') also trip it.

Related errors

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

Appendix: 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 52c9bd7908)