Tencent/WeKnora · error

KB hybrid search failed: %w

Error message

KB hybrid search failed: %w

What it means

vectorSearchViaKB delegates the vector part of message search to the knowledge base service's HybridSearch. If that call fails, the whole KB-backed vector search fails with this wrapper. It indicates a problem inside the KB service (index unavailable, bad KB config, embedding provider failure), not in the message query itself.

Source

Thrown at internal/application/service/message.go:642

	cfg := s.getChatHistoryConfig(ctx)
	if cfg == nil {
		return nil, nil // Chat history KB not configured, skip vector search
	}

	// Read global retrieval config for search parameters
	rc := s.getRetrievalConfig(ctx)

	// Use KB HybridSearch with vector-only mode (keyword search is done separately on the messages table)
	searchParams := types.SearchParams{
		QueryText:            params.Query,
		MatchCount:           rc.GetEffectiveEmbeddingTopK(),
		VectorThreshold:      rc.GetEffectiveVectorThreshold(),
		DisableKeywordsMatch: true, // We handle keyword search separately on the messages table
	}

	kbResults, err := s.kbService.HybridSearch(ctx, cfg.KnowledgeBaseID, searchParams)
	if err != nil {
		return nil, fmt.Errorf("KB hybrid search failed: %w", err)
	}

	if len(kbResults) == 0 {
		return nil, nil
	}

	// Rerank results if a rerank model is configured
	kbResults = s.rerankResults(ctx, rc, params.Query, kbResults)
	if len(kbResults) == 0 {
		return nil, nil
	}

	// Map KB search results back to messages via knowledge_id
	knowledgeIDs := make([]string, 0, len(kbResults))
	scoreByKnowledgeID := make(map[string]float64)
	for _, r := range kbResults {
		knowledgeIDs = append(knowledgeIDs, r.KnowledgeID)
		scoreByKnowledgeID[r.KnowledgeID] = r.Score

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped HybridSearch error to see whether it is config, embedding-provider, or index related.
2. Verify cfg.KnowledgeBaseID exists and is enabled for the tenant.
3. Confirm the embedding provider credentials/quotas and vector store health.
4. Add a fallback to pure keyword search on messages table when KB vector search fails.

Example fix

// before
kbResults, err := s.kbService.HybridSearch(ctx, cfg.KnowledgeBaseID, searchParams)
if err != nil {
    return nil, fmt.Errorf("KB hybrid search failed: %w", err)
}
// after
kbResults, err := s.kbService.HybridSearch(ctx, cfg.KnowledgeBaseID, searchParams)
if err != nil {
    logger.Warnf(ctx, "KB hybrid search failed, falling back to keyword: %v", err)
    return s.keywordSearchFallback(ctx, params)
}

if cfg == nil || !cfg.Enabled || cfg.KnowledgeBaseID == "" {
    // skip KB vector search, go straight to keyword search
}

func kbReady(cfg *types.ChatHistoryConfig) bool {
    return cfg != nil && cfg.Enabled && cfg.KnowledgeBaseID != ""
}

msgs, err := svc.SearchMessages(ctx, params)
if err != nil && strings.Contains(err.Error(), "KB hybrid search failed") {
    msgs, err = keywordOnlySearch(ctx, params) // graceful degradation
}

When it happens

Trigger: Calling SearchMessages with vector/KB search enabled when kbService.HybridSearch errors: knowledge base ID missing or deleted, embedding provider unreachable, vector index down, or invalid searchParams (bad threshold).

Common situations: KB not provisioned for the tenant (cfg.KnowledgeBaseID points at a removed KB); embedding API quota/key issues; vector DB outage; misconfigured effective vector threshold after settings change.

Related errors

• failed to get messages by knowledge IDs: %w
• knowledge_id is required
• knowledge service is unavailable
• failed to marshal query embedding: %w
• get knowledge base: %w

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