gohugoio/hugo · error

project config…

Error message

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

What it means

Returned by CompileConfig when markup.goldmark.renderHooks.image.useEmbedded is not one of the four allowed modes: always, auto, fallback, never. The check uses slices.Contains against the canonical constant set; any other value (including typos and the legacy boolean 'true'/'false') is rejected.

Solutions

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

Example fix

// before
[markup.goldmark.renderHooks.image]
useEmbedded = "default"
// after
[markup.goldmark.renderHooks.image]
useEmbedded = "fallback"

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

When it happens

Trigger: Setting `markup.goldmark.renderHooks.image.useEmbedded = "default"`, `"true"`, `"always-when-set"`, or any string outside {always, auto, fallback, never}.

Common situations: Upgrading from a pre-0.148 config that used the boolean `enableDefault`, then manually rewriting the key and using an invalid string; or copy-pasting docs from an incompatible Hugo version.

Related errors

• project config markup.goldmark.renderHooks.link.useEmbedded…
• goldmark
• rst
• --appendPort=false not supported when in multihost mode
• cache dir contains unresolved placeholders

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

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