gohugoio/hugo · error

version name cannot be empty

Error message

version name cannot be empty

What it means

Raised while initializing the content versions config (hugolib/versions/versions.go:165) when a key in the versions map is the empty string. Every version must have a non-empty name because the name becomes a path identifier and the map key for version configs.

Source

Thrown at hugolib/versions/versions.go:165

const defaultContentVersionFallback = "v1.0.0"

func (r *VersionsInternal) init(defaultContentVersion string) error {
	if r.versionConfigs == nil {
		r.versionConfigs = make(map[string]VersionConfig)
	}
	defaultContentVersionProvided := defaultContentVersion != ""
	if len(r.versionConfigs) == 0 {
		if defaultContentVersion == "" {
			defaultContentVersion = defaultContentVersionFallback
		}
		// Add a default version.
		r.versionConfigs[defaultContentVersion] = VersionConfig{}
	}

	var defaultSeen bool
	for k, v := range r.versionConfigs {
		if k == "" {
			return errors.New("version name cannot be empty")
		}
		if err := paths.ValidateIdentifier(k); err != nil {
			return fmt.Errorf("version name %q is invalid: %s", k, err)
		}

		var isDefault bool
		if k == defaultContentVersion {
			isDefault = true
			defaultSeen = true
		}

		// Ignore error, this may not be a semver version.
		parsedVersion, _ := version.ParseVersion(k)

		r.Sorted = append(r.Sorted, VersionInternal{Name: k, parsedVersion: parsedVersion, Default: isDefault, VersionConfig: v})
	}

	// Sort by weight if set, then semver descending.

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Find the empty key in your versions config block and give it a real name (e.g. "v1.0.0").
2. Remove the malformed entry if it was accidental.
3. Validate generated config (hugo config) if the versions block is produced by tooling.

Example fix

# before (hugo.yaml)
versions:
  "": {}
  v2: {}
# after
versions:
  v1: {}
  v2: {}

for _, v := range versionsConfig {
    if strings.TrimSpace(v.Name) == "" {
        return fmt.Errorf("version entry missing name")
    }
}

When it happens

Trigger: A versions/versionConfigs map in site config containing an empty-string key — e.g. a YAML/TOML versions block with a blank key or an entry defined as "": {...}.

Common situations: Hand-edited YAML where a list/map entry lost its key, templated config generation emitting an empty version name, or converting config formats and dropping a key. This is a newer versioned-content feature, so misreading its docs while adopting it is common.

Related errors

• version name %q is invalid: %s
• redirects must have either From or FromRe set
• failed to create config from result: %w
• failed to create config: %w
• failed to decode %q: %w

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