gohugoio/hugo · error

role name %q is invalid: %s

Error message

role name %q is invalid: %s

What it means

Raised when a configured role name fails `paths.ValidateIdentifier` during roles-registry construction. Role names are used as path/identifier components in Hugo, so they must conform to Hugo's identifier rules (letters, digits, and a limited set of separators — no spaces or exotic characters). The wrapped `%s` gives the specific validation failure.

Source

Thrown at hugolib/roles/roles.go:154

		r.roleConfigs = make(map[string]RoleConfig)
	}
	defaultContentRoleProvided := defaultContentRole != ""
	if len(r.roleConfigs) == 0 {
		// Add a default role.
		if defaultContentRole == "" {
			defaultContentRole = defaultContentRoleFallback
		}
		r.roleConfigs[defaultContentRole] = RoleConfig{}
	}

	var defaultSeen bool
	for k, v := range r.roleConfigs {
		if k == "" {
			return "", errors.New("role name cannot be empty")
		}

		if err := paths.ValidateIdentifier(k); err != nil {
			return "", fmt.Errorf("role name %q is invalid: %s", k, err)
		}

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

		r.Sorted = append(r.Sorted, RoleInternal{Name: k, Default: isDefault, RoleConfig: v})
	}

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

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Rename the role key to a simple identifier (lowercase letters, digits, hyphens) and read the wrapped message for the exact rule violated.
2. If you need a display name, keep the key as a slug and put the friendly name in the role's config fields.
3. Re-run `hugo` after fixing; the error names the offending key with %q so it's directly searchable in your config.

Example fix

# before
roles:
  "Site Admin!": {}

# after
roles:
  site-admin: {}

var validRole = regexp.MustCompile(`^[a-z][a-z0-9_-]*$`)
if !validRole.MatchString(name) {
    return fmt.Errorf("invalid role name %q", name)
}

if err != nil {
    // surface the embedded reason (%s) to the user; do not retry with the same name
}

When it happens

Trigger: A `roles` config entry keyed with characters that `paths.ValidateIdentifier` rejects, e.g. `roles: { 'my role!': {} }` or names containing slashes, spaces, or uppercase/unicode characters the validator disallows.

Common situations: Using human-readable display names ("Site Admin") as the role key instead of a slug; migrating role definitions from another system that allows spaces; punctuation typos in config keys.

Related errors

• role 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/ae584f36bc2802db.json. Report an issue: GitHub ↗.