the configured defaultContentVersion

Error message

the configured defaultContentVersion %q does not exist

What it means

The site config set a defaultContentVersion, but after scanning all configured version keys none matched it (versions.go:198-200). Hugo requires defaultContentVersion to correspond to an existing version name; when it does not, initialization fails. If defaultContentVersion is left empty, Hugo picks a sensible default instead of erroring.

Solutions

Ensure the defaultContentVersion value exactly matches one key in the [versions] map (case-sensitive, normalized).
If unsure which versions exist, print the configured version keys and align the default.
Leave defaultContentVersion empty to let Hugo auto-select the first version.

Example fix

// before
defaultContentVersion = "v2.0.0"
[versions]
"v1.0.0" = {}

// after (add the version, or fix the default)
defaultContentVersion = "v2.0.0"
[versions]
"v1.0.0" = {}
"v2.0.0" = { weight = 10 }

Defensive patterns

Strategy: validation

Validate before calling

func validateDefaultVersion(defaultVersion string, configured map[string]VersionConfig) error {
    if defaultVersion == "" {
        return nil // Hugo auto-selects
    }
    if _, ok := configured[defaultVersion]; !ok {
        return fmt.Errorf("the configured defaultContentVersion %q does not exist", defaultVersion)
    }
    return nil
}

Prevention

Add a version to the [versions] map before setting it as defaultContentVersion.
After renaming a version, update defaultContentVersion to match.
Leave defaultContentVersion empty to let Hugo pick the first version.

When it happens

Trigger: Setting defaultContentVersion = "v2.0.0" in config while the [versions] block only defines "v1.0.0"; a typo in the default version name; referencing a version after deleting it from the versions config.

Common situations: Promoting a new default version in defaultContentVersion before adding it to [versions]; renaming a version key without updating defaultContentVersion; environment-specific config overriding versions inconsistently.

Related errors

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

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