chenhg5/cc-connect · error

config: %s.card_mode must be "legacy" or "rich"

Error message

config: %s.card_mode must be "legacy" or "rich"

What it means

CC-Connect validates each project's card rendering mode at config load time. When `[projects.display].card_mode` is set to anything other than "legacy" or "rich" (case-insensitive, whitespace-trimmed), validateDisplayConfig rejects the config. It selects between the old and new card renderers.

Source

Thrown at config/config.go:1090

	return nil
}

func validateDisplayConfig(prefix string, display *DisplayConfig) error {
	if display == nil {
		return nil
	}
	if display.Mode != nil {
		switch *display.Mode {
		case DisplayModeFull, DisplayModeCompact, DisplayModeQuiet:
		default:
			return fmt.Errorf("config: %s.mode must be \"full\", \"compact\", or \"quiet\"", prefix)
		}
	}
	if display.CardMode != nil {
		switch strings.ToLower(strings.TrimSpace(*display.CardMode)) {
		case "legacy", "rich":
		default:
			return fmt.Errorf("config: %s.card_mode must be \"legacy\" or \"rich\"", prefix)
		}
	}
	if display.HistoryMaxLen != nil && *display.HistoryMaxLen < 0 {
		return fmt.Errorf("config: %s.history_max_len must be >= 0", prefix)
	}
	return nil
}

var supportedReferenceAgents = map[string]struct{}{
	"all":        {},
	"codex":      {},
	"claudecode": {},
}

var supportedReferencePlatforms = map[string]struct{}{
	"all":    {},
	"feishu": {},
	"weixin": {},

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set card_mode to "rich" (new renderer) or "legacy" (old renderer)
2. Fix spelling/typos; values are lowercased and trimmed but must match one of the two words
3. Delete the card_mode line to use the default

Example fix

# before
[projects.display]
card_mode = "v2"

# after
[projects.display]
card_mode = "rich"

cm := strings.ToLower(strings.TrimSpace(cardMode))
if cm != "legacy" && cm != "rich" {
    return fmt.Errorf("card_mode %q must be legacy or rich", cardMode)
}

func isValidCardMode(m string) bool { cm := strings.ToLower(strings.TrimSpace(m)); return cm == "legacy" || cm == "rich" }

When it happens

Trigger: Loading config.toml where a project's `[projects.*.display] card_mode` is a misspelled or outdated value such as "card", "new", "v2", or "classic".

Common situations: Following an old blog post or migration guide that used a pre-release name for the rich card mode; typos when hand-editing; confusion with other boolean-ish card toggles.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• config: %s.mode must be "full", "compact", or "quiet"
• invalid TOML: %w
• tmux: 'session' option is required (name of the tmux session
• reload config: %w
• config: relay.visibility must be "full", "summary", or "none

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