gohugoio/hugo · error

the configured defaultContentRole

Error message

the configured defaultContentRole %q does not exist

What it means

Raised by RolesInternal.init (roles.go:183) when defaultContentRole is explicitly provided in config but does not match any key in the roleConfigs map. The default role must be one of the declared roles; if `defaultSeen` is false after iterating and the user supplied a default, this fires.

Solutions

1. Set defaultContentRole to an existing role key, or omit it so Hugo auto-picks the first role.
2. Fix typos and casing — the value must exactly match a declared role key.
3. If you removed the intended default role, choose a new one or delete the defaultContentRole setting.

Example fix

# before
[roles]
  [roles.editor]
    weight = 1
defaultContentRole = "main"

# after
defaultContentRole = "editor"

# Ensure defaultContentRole exists among declared role keys.
roles=$(awk '/^\[roles\./ {gsub(/\[roles\.|\]/,""); print}' hugo.toml | sort -u)
default=$(awk -F= '/defaultContentRole/ {gsub(/[ "]/,"",$2); print $2}' hugo.toml)
echo "$roles" | grep -qx "$default" || echo "default '$default' not declared"

When it happens

Trigger: Setting `defaultContentRole = "main"` while the roles map only contains `editor` and `guest`; a typo in the default role name; renaming a role without updating the default reference.

Common situations: Refactoring role names and forgetting the default; mismatched casing (default set to `Editor` while key is `editor` — note identifiers must be lowercase anyway); copying config between projects with different role sets.

Related errors

• role name is invalid
• cardinalityThreshold threshold must be between 0 and 100
• failed to compile Glob
• failed to decode segments
• markup must not be set, use mediaType

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

Appendix: source

Thrown at hugolib/roles/roles.go:183

	// 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 {
			return true
		}
		if ri.Weight == 0 {
			return false
		}
		return ri.Weight < rj.Weight
	})

	if !defaultSeen {
		if defaultContentRoleProvided {
			return "", fmt.Errorf("the configured defaultContentRole %q does not exist", defaultContentRole)
		}
		// If no default role is set, we set the first one.
		first := r.Sorted[0]
		first.Default = true
		r.roleConfigs[first.Name] = first.RoleConfig
		r.Sorted[0] = first
		defaultContentRole = first.Name
	}

	return defaultContentRole, nil
}

func (r RolesInternal) Has(role string) bool {
	_, found := r.roleConfigs[role]
	return found
}

func DecodeConfig(defaultContentRole string, m map[string]any) (*config.ConfigNamespace[map[string]RoleConfig, RolesInternal], string, error) {

View on GitHub (pinned to 52c9bd7908)