What causes "role name cannot be empty" in gohugoio/hugo?

Inspect the `roles` block in your site configuration and remove/rename any entry with an empty key.

role name cannot be empty

Error message

role name cannot be empty

What it means

Raised while building Hugo's roles registry in hugolib/roles/roles.go: the map of configured role names is iterated and an empty-string key is rejected outright. Role names become identifiers used in sorting, lookups, and default-role resolution, so an empty name is meaningless and fails fast during config load.

Source

Thrown at hugolib/roles/roles.go:150

const defaultContentRoleFallback = "guest"

func (r *RolesInternal) init(defaultContentRole string) (string, error) {
	if r.roleConfigs == nil {
		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]

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Inspect the `roles` block in your site configuration and remove/rename any entry with an empty key.
If config is generated, fix the generator so it never emits empty map keys.
Run `hugo config` to view the merged configuration and locate where the empty key originates.

Example fix

# before (hugo.yaml)
roles:
  "": {}
  editor: {}

# after
roles:
  member: {}
  editor: {}

Defensive patterns

Strategy: validation

Validate before calling

name = strings.TrimSpace(name)
if name == "" {
    return errors.New("role name required")
}

Prevention

Trim whitespace on role names from config/front matter before passing them in
Reject empty strings at the point user input is read, not deep in site build
Add a config-validation step in CI that checks all declared roles are non-empty

When it happens

Trigger: A `roles` section in site configuration containing an entry whose key is the empty string — e.g. `roles: { '': {...} }` in YAML, or a config-merging/templating step that emits an empty map key.

Common situations: YAML quirks producing an empty key (a stray `"":` or a null key coerced to ""), generated configuration (scripts writing hugo.yaml/json) emitting empty keys, or accidental empty quotes when renaming a role.

Related errors

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