chenhg5/cc-connect · error

config: .references.normalize_agents has unsupported value

Error message

config: %s.references.normalize_agents has unsupported value %q

What it means

CC-Connect validates the `[projects.references].normalize_agents` list against a fixed allowlist ("all", "codex", "claudecode") at config load time. Any entry outside the allowlist makes validateReferenceConfig reject the config, quoting the offending value.

Solutions

1. Use only "all", "codex", or "claudecode" in normalize_agents
2. Fix the typo by comparing against the supported list in the error docs
3. Remove the unsupported entry; use ["all"] to cover every supported agent

Example fix

# before
[projects.references]
normalize_agents = ["gemini"]

# after
[projects.references]
normalize_agents = ["all"]

var supportedRefAgents = map[string]bool{"all": true, "codex": true, "claudecode": true}
for _, v := range refs.NormalizeAgents {
    if !supportedRefAgents[strings.ToLower(strings.TrimSpace(v))] {
        return fmt.Errorf("normalize_agents entry %q unsupported", v)
    }
}

func isSupportedRefAgent(v string) bool {
    switch strings.ToLower(strings.TrimSpace(v)) {
    case "all", "codex", "claudecode":
        return true
    }
    return false
}

When it happens

Trigger: Loading config.toml where normalize_agents contains an agent name not in the allowlist, e.g. normalize_agents = ["gemini"] or a misspelled "claduecode". Matching is case-insensitive and whitespace-trimmed, so casing is not the issue — only the name itself.

Common situations: Assuming all registered agents are reference-normalizable; typos; referencing an agent added in a newer/older cc-connect version where the allowlist differs.

Related errors

• config: .references.display_path has unsupported value
• config: .references.enclosure_style has unsupported value
• config: .references.marker_style has unsupported value
• config: .references.render_platforms has unsupported value
• app_id and app_secret are required

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

Appendix: source

Thrown at config/config.go:1140

	"none":  {},
	"ascii": {},
	"emoji": {},
}

var supportedReferenceEnclosureStyles = map[string]struct{}{
	"":          {},
	"none":      {},
	"bracket":   {},
	"angle":     {},
	"fullwidth": {},
	"code":      {},
}

func validateReferenceConfig(prefix string, rc ReferenceConfig) error {
	for _, v := range rc.NormalizeAgents {
		key := strings.ToLower(strings.TrimSpace(v))
		if _, ok := supportedReferenceAgents[key]; !ok {
			return fmt.Errorf("config: %s.references.normalize_agents has unsupported value %q", prefix, v)
		}
	}
	for _, v := range rc.RenderPlatforms {
		key := strings.ToLower(strings.TrimSpace(v))
		if _, ok := supportedReferencePlatforms[key]; !ok {
			return fmt.Errorf("config: %s.references.render_platforms has unsupported value %q", prefix, v)
		}
	}
	if _, ok := supportedReferenceDisplayPaths[strings.ToLower(strings.TrimSpace(rc.DisplayPath))]; !ok {
		return fmt.Errorf("config: %s.references.display_path has unsupported value %q", prefix, rc.DisplayPath)
	}
	if _, ok := supportedReferenceMarkerStyles[strings.ToLower(strings.TrimSpace(rc.MarkerStyle))]; !ok {
		return fmt.Errorf("config: %s.references.marker_style has unsupported value %q", prefix, rc.MarkerStyle)
	}
	if _, ok := supportedReferenceEnclosureStyles[strings.ToLower(strings.TrimSpace(rc.EnclosureStyle))]; !ok {
		return fmt.Errorf("config: %s.references.enclosure_style has unsupported value %q", prefix, rc.EnclosureStyle)
	}
	return nil

View on GitHub (pinned to 4000b2338a)