chenhg5/cc-connect · error

config: %s.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.

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)

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: %s.references.render_platforms has unsupported value
• config: %s.references.display_path has unsupported value %q
• config: %s.references.marker_style has unsupported value %q
• config: %s.references.enclosure_style has unsupported value
• tmux: 'session' option is required (name of the tmux session

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