gohugoio/hugo · error

the configured defaultContentVersion %q does not exist

Error message

the configured defaultContentVersion %q does not exist

What it means

Raised at the end of versions init (hugolib/versions/versions.go:200) when defaultContentVersion was explicitly set in config but no key in the versions map matches it. If defaultContentVersion is unset Hugo silently picks the first sorted version instead — the error only fires for an explicit, dangling reference.

Source

Thrown at hugolib/versions/versions.go:200

	// Sort by weight if set, then semver descending.
	sort.SliceStable(r.Sorted, func(i, j int) bool {
		ri, rj := r.Sorted[i], r.Sorted[j]
		if ri.Weight == rj.Weight {
			return ri.parsedVersion.Compare(rj.parsedVersion) < 0
		}
		if rj.Weight == 0 {
			return true
		}
		if ri.Weight == 0 {
			return false
		}
		return ri.Weight < rj.Weight
	})

	if !defaultSeen {
		if defaultContentVersionProvided {
			return fmt.Errorf("the configured defaultContentVersion %q does not exist", defaultContentVersion)
		}
		// If no default version is set, we set the first one.
		first := r.Sorted[0]
		first.Default = true
		r.versionConfigs[first.Name] = first.VersionConfig
		r.Sorted[0] = first
	}

	return nil
}

func (r VersionsInternal) Has(version string) bool {
	_, found := r.versionConfigs[version]
	return found
}

func DecodeConfig(defaultContentVersion string, m map[string]any) (*config.ConfigNamespace[map[string]VersionConfig, VersionsInternal], error) {
	return config.DecodeNamespace[map[string]VersionConfig](m, func(in any) (VersionsInternal, any, error) {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Make defaultContentVersion exactly match one of the keys in your versions map (case-sensitive).
2. Add the missing version entry to the versions map if it was removed by mistake.
3. Or delete defaultContentVersion to let Hugo pick the first version by weight/semver order.
4. Run `hugo config` to see the merged versions map if overlays are involved.

Example fix

# before
defaultContentVersion = "v3"
[versions.v1]
[versions.v2]
# after
defaultContentVersion = "v2"
[versions.v1]
[versions.v2]

names := map[string]bool{}
for _, v := range versionsConfig { names[v.Name] = true }
if d := cfg.DefaultContentVersion; d != "" && !names[d] {
    return fmt.Errorf("defaultContentVersion %q not among defined versions", d)
}

When it happens

Trigger: Config with defaultContentVersion = "vX" where the versions map has no "vX" entry — the comparison is exact, so a case or spelling mismatch ("V2" vs "v2") also triggers it.

Common situations: Renaming or deleting a version in the versions block without updating defaultContentVersion, typos, or environment-specific config overlays that override the versions map but keep an old default.

Related errors

• version name cannot be empty
• version name %q is invalid: %s
• language %q not found
• unsupported format: %q
• failed to create workingDir: %w

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