Tencent/WeKnora · error

failed to build tag map: %w

Error message

failed to build tag map: %w

What it means

ExportFAQEntries builds a tag_id -> tag_name map via buildTagMap so exported CSV rows carry readable tag names; failure is wrapped with this message. The chunks were listed successfully but tag lookup failed, so the export cannot render tag columns. Failures originate in the tag repository (DB query over the tenant's tags).

Source

Thrown at internal/application/service/knowledge_faq.go:1468

	faqKnowledge, err := s.findFAQKnowledge(ctx, tenantID, kb.ID)
	if err != nil {
		return nil, err
	}
	if faqKnowledge == nil {
		// Return empty CSV with headers only
		return s.buildFAQCSV(nil, nil), nil
	}

	// Get all FAQ chunks
	chunks, err := s.chunkRepo.ListAllFAQChunksForExport(ctx, tenantID, faqKnowledge.ID)
	if err != nil {
		return nil, fmt.Errorf("failed to list FAQ chunks: %w", err)
	}

	// Build tag map for tag_id -> tag_name conversion
	tagMap, err := s.buildTagMap(ctx, tenantID, kbID)
	if err != nil {
		return nil, fmt.Errorf("failed to build tag map: %w", err)
	}

	return s.buildFAQCSV(chunks, tagMap), nil
}

// ExportFAQEntriesJSON 以 JSON 数组形式导出 FAQ 知识库下的全部条目，
// 字段与 FAQEntryPayload 兼容，便于"导出 → 编辑 → 重新 append 导入"循环。
func (s *knowledgeService) ExportFAQEntriesJSON(ctx context.Context, kbID string) ([]byte, error) {
	kb, err := s.validateFAQKnowledgeBase(ctx, kbID)
	if err != nil {
		return nil, err
	}

	tenantID := ctx.Value(types.TenantIDContextKey).(uint64)
	faqKnowledge, err := s.findFAQKnowledge(ctx, tenantID, kb.ID)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped tag-repo error and DB health; retry the export after connectivity is restored.
2. Verify the tag table and tenant-scoped indexes exist and are healthy.
3. As a workaround, export via JSON and map tag IDs to names client-side from the tag API.
4. Increase export timeouts if the tag table is large.

Example fix

// resilient client-side fallback
tagMap, err := svc.BuildTagMap(ctx, tenantID, kbID)
if err != nil {
	log.Warn("tag map unavailable, exporting with raw tag IDs")
	tagMap = map[string]string{}
}

// confirm tags are queryable before export
if _, err := tagRepo.GetByIDs(ctx, tenantID, []string{"__probe__"}); err != nil && !errors.Is(err, ErrNotFound) {
	return fmt.Errorf("tag store unavailable: %w", err)
}

data, err := svc.ExportFAQEntries(ctx, kbID, page, tagUUIDs, keyword, 0, "", "")
if err != nil && strings.Contains(err.Error(), "failed to build tag map") {
	// fallback: export JSON and resolve tag names client-side
	jsonBytes, jErr := svc.ExportFAQEntriesJSON(ctx, kbID)
	if jErr == nil {
		data = resolveTagsClientSide(jsonBytes)
	}
}

When it happens

Trigger: Calling ExportFAQEntries when buildTagMap's tag repository query fails (DB error, timeout, context cancellation). This requires FAQ entries with TagIDs set; a KB with untagged entries and a tag-query failure can still hit it since buildTagMap runs unconditionally.

Common situations: Tag table corruption or missing rows; DB connectivity loss mid-export; very large tag tables making the map build slow enough to hit context deadlines; permission/tenant scoping errors in the tag repo.

Related errors

• failed to list FAQ chunks: %w
• failed to ensure FAQ knowledge: %w
• failed to create chunk: %w
• failed to update chunk status: %w
• failed to get embedding model: %w

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