gohugoio/hugo · error

version name %q is invalid: %s

Error message

version name %q is invalid: %s

What it means

Raised right after the empty-name check (hugolib/versions/versions.go:168) when a version name fails paths.ValidateIdentifier. Version names are used as path segments/identifiers, so they must be valid identifiers; the wrapped %s explains which rule was violated.

Source

Thrown at hugolib/versions/versions.go:168

	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.
	sort.SliceStable(r.Sorted, func(i, j int) bool {
		ri, rj := r.Sorted[i], r.Sorted[j]
		if ri.Weight == rj.Weight {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Rename the version to a plain identifier: lowercase letters, digits, dots, hyphens (e.g. v1.2.0).
2. Read the appended validation message for the exact offending character and remove it.
3. If you want a display title, keep the key simple and set a title inside that version's config.

Example fix

# before
versions:
  "v 1.0/beta": {}
# after
versions:
  v1.0-beta: {}

var validVersion = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
for _, v := range versionsConfig {
    if !validVersion.MatchString(v.Name) {
        return fmt.Errorf("invalid version name %q", v.Name)
    }
}

When it happens

Trigger: A versions config key containing characters rejected by paths.ValidateIdentifier — e.g. spaces, slashes, uppercase-or-symbol combinations disallowed for Hugo identifiers (like "v 1.0" or "v1/beta").

Common situations: Naming versions after human-readable release titles ("Release 2024"), including slashes to imply nesting, or copying git tag names with characters invalid as path identifiers.

Related errors

• version name cannot be empty
• 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/ef7dc559a2018d53.json. Report an issue: GitHub ↗.