Tencent/WeKnora · error

invalid follow-up suggestion category %q

Error message

invalid follow-up suggestion category %q

What it means

This error is thrown by the follow-up suggestion config validator (Validate on the custom agent config) when a follow-up suggestion category is not one of the three allowed values: clarify, deepen, action. The library restricts FollowUps.Categories to this fixed enum so downstream suggestion rendering remains well-defined.

Source

Thrown at internal/types/custom_agent.go:408

	}
	if !oneOf(c.FollowUps.Mode, SuggestionModeGenerated, SuggestionModeKnowledge, SuggestionModeHybrid) {
		return fmt.Errorf("invalid follow-up suggestion mode %q", c.FollowUps.Mode)
	}
	for i, item := range c.Starters.Items {
		trimmed := strings.TrimSpace(item)
		if trimmed == "" {
			return fmt.Errorf("starter suggestion %d cannot be empty", i+1)
		}
		if len([]rune(trimmed)) > 200 {
			return fmt.Errorf("starter suggestion %d exceeds 200 characters", i+1)
		}
	}
	if len([]rune(strings.TrimSpace(c.FollowUps.AdditionalInstruction))) > 2000 {
		return fmt.Errorf("follow-up additional_instruction exceeds 2000 characters")
	}
	for _, category := range c.FollowUps.Categories {
		if !oneOf(category, SuggestionCategoryClarify, SuggestionCategoryDeepen, SuggestionCategoryAction) {
			return fmt.Errorf("invalid follow-up suggestion category %q", category)
		}
	}
	return nil
}

func oneOf(value string, allowed ...string) bool {
	for _, candidate := range allowed {
		if value == candidate {
			return true
		}
	}
	return false
}

// ResolveChatParserEngine returns the agent-configured parser engine for a
// chat attachment file type, or the type-level default when no rule matches.
// Mirrors ParserEngineConfig.ResolveChatParserEngine.
func (c *CustomAgentConfig) ResolveChatParserEngine(fileType string) string {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Replace the offending category value with one of the allowed values: clarify, deepen, action
2. Check exact spelling and case of each entry in follow_ups.categories
3. If the old category no longer exists, map it to the closest allowed category or remove it
4. Pre-validate categories against the SuggestionCategory constants before submitting the config

Example fix

// before
c.FollowUps.Categories = []string{"summarize", "clarify"}
// after
c.FollowUps.Categories = []string{"clarify", "deepen"}

var validCategories = map[string]bool{"clarify": true, "deepen": true, "action": true}
func categoriesValid(cats []string) bool {
    for _, c := range cats { if !validCategories[c] { return false } }
    return true
}

func isSuggestionCategory(s string) bool {
    return s == SuggestionCategoryClarify || s == SuggestionCategoryDeepen || s == SuggestionCategoryAction
}

if err := cfg.Validate(); err != nil {
    var msg string
    if _, err := fmt.Sscanf(err.Error(), "invalid follow-up suggestion category %q", &msg); err == nil {
        // surface msg to the user as an invalid category
    }
}

When it happens

Trigger: Calling the custom agent config validation (e.g. via agent create/update APIs) with c.FollowUps.Categories containing a value other than "clarify", "deepen", or "action" — including empty strings, typos, or old/renamed category values.

Common situations: Hand-written agent config JSON with a misspelled category (e.g. "summary", "followup"), categories migrated from an older schema version that used different names, or programmatic generation injecting raw user input as a category.

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

• API key is required for Exa provider
• model ID cannot be empty
• unknown credential field:
• member_limit must be >= 0
• cannot request upgrade to same or lower role

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/11dab2c4b5206bdb. Report an issue: GitHub.