the configured defaultContentRole %q does not exist

Error message

the configured defaultContentRole %q does not exist

What it means

After collecting all configured roles, Hugo checks that the explicitly configured `defaultContentRole` matches one of them. If the user provided a `defaultContentRole` and no role with that name exists in the roles map, config load fails with this error. (When no default is provided, Hugo silently promotes the first sorted role instead.)

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 8a468df065)

Solutions

Make `defaultContentRole` exactly match one of the keys under `roles` (case-sensitive).
Add the missing role definition under `roles` if it was removed accidentally.
Remove `defaultContentRole` entirely to let Hugo pick the first role automatically.
Check merged config with `hugo config` to see which roles survive environment merging.

Example fix

# before
defaultContentRole = "members"
[roles.member]

# after
defaultContentRole = "member"
[roles.member]

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := definedRoles[cfg.DefaultContentRole]; !ok {
    return fmt.Errorf("defaultContentRole %q not in roles %v", cfg.DefaultContentRole, keys(definedRoles))
}

Prevention

Always declare defaultContentRole as one of the roles defined in the same config
Cross-check role references in a config-validation CI step before deploying
When renaming a role, grep the config for all references (defaultContentRole, per-page roles) in the same commit

When it happens

Trigger: Setting `defaultContentRole = "x"` in site config where `x` is not a key under `roles`; renaming or deleting a role without updating `defaultContentRole`; environment-specific config overriding `roles` but not `defaultContentRole`.

Common situations: Refactoring role names and missing one reference; per-environment config files (config/production) redefining the roles map so the default from the base config no longer exists; case mismatch between the default and the role key.

Related errors

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