config: %s.users.default_role %q does not match any defined

Error message

config: %s.users.default_role %q does not match any defined role

What it means

This error means the project's users.default_role names a role that is not defined in that same users block. The default role is what unlisted users fall back to, so it must reference an existing role key; otherwise fallback would be undefined.

Source

Thrown at config/config.go:1192

		}
		for _, uid := range rc.UserIDs {
			if uid == "*" {
				wildcardCount++
				continue
			}
			lower := strings.ToLower(uid)
			if prev, dup := seenUserIDs[lower]; dup {
				return fmt.Errorf("config: %s.users: user %q appears in both role %q and %q", prefix, uid, prev, roleName)
			}
			seenUserIDs[lower] = roleName
		}
	}
	if wildcardCount > 1 {
		return fmt.Errorf("config: %s.users: wildcard user_ids=[\"*\"] appears in multiple roles", prefix)
	}
	if u.DefaultRole != "" {
		if _, ok := u.Roles[u.DefaultRole]; !ok {
			return fmt.Errorf("config: %s.users.default_role %q does not match any defined role", prefix, u.DefaultRole)
		}
	}
	return nil
}

// SaveActiveProvider persists the active provider name for a project.
// It uses surgical text editing to preserve comments and unknown fields.
func SaveActiveProvider(projectName, providerName string) error {
	configMu.Lock()
	defer configMu.Unlock()
	return patchProjectAgentOption(projectName, "provider", providerName)
}

// SaveProviderModel persists the selected model for a provider in a project.
// It first looks in the project's inline providers, then falls back to
// global [[providers]] if the provider is referenced via provider_refs.
// Uses surgical text editing to preserve comments and unknown fields.
func SaveProviderModel(projectName, providerName, model string) error {

View on GitHub (pinned to 4000b2338a)

Solutions

Set default_role to an exact role key that exists in the same users block
Or define the missing role under the roles table
Check for typos/case differences between default_role and the role names

Example fix

// before
default_role = "member"
roles.user.user_ids = ["*"]
// after
default_role = "user"
roles.user.user_ids = ["*"]

Defensive patterns

Strategy: validation

Validate before calling

if u.DefaultRole != "" {
	if _, ok := u.Roles[u.DefaultRole]; !ok {
		return fmt.Errorf("default_role %q undefined", u.DefaultRole)
	}
}

Try / catch

if err := loadConfig(path); err != nil {
	if strings.Contains(err.Error(), "default_role") {
		// align default_role with a defined role key
	}
	return err
}

Prevention

Rename roles and default_role in the same edit
Generate default_role from the roles map keys in tooling
Keep role names lowercase snake to avoid case mismatches

When it happens

Trigger: Config load/validation when u.DefaultRole is non-empty and u.Roles[u.DefaultRole] does not exist — e.g. default_role = "member" but only roles "user" and "admin" are defined, or a typo/renamed role.

Common situations: Renaming a role in config but forgetting to update default_role; adding default_role before ever defining the roles table; copy-pasting a users block between projects and trimming roles.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/d9ebb99c2ba91776. Report an issue: GitHub.