Tencent/WeKnora · error

failed to list FAQ chunks: %w

Error message

failed to list FAQ chunks: %w

What it means

ExportFAQEntries lists all FAQ chunks for export via chunkRepo.ListAllFAQChunksForExport and wraps failures with this message. It means the underlying query over the FAQ knowledge's chunks failed (DB error), so the CSV export aborts and returns no data. Empty result sets are NOT an error — they export an empty CSV.

Source

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

	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
	}
	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
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped DB error; fix connectivity or timeout issues and retry the export.
2. Increase the request/export timeout for large knowledge bases, or export via the JSON API in pages.
3. Verify DB indexes on (tenant_id, knowledge_id, chunk_type) supporting ListAllFAQChunksForExport.
4. Retry during a lower-traffic window if lock contention/timeouts are the cause.

Example fix

// before: gateway timeout kills large exports
client := &http.Client{Timeout: 10 * time.Second}
// after
client := &http.Client{Timeout: 5 * time.Minute} // allow full FAQ export scan

if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("database unavailable; postpone FAQ export: %w", err)
}
if deadline, ok := ctx.Deadline(); ok && time.Until(deadline) < 30*time.Second {
	return errors.New("context deadline too short for FAQ export")
}

data, err := svc.ExportFAQEntries(ctx, kbID, page, tagUUIDs, keyword, 0, "", "")
if err != nil && strings.Contains(err.Error(), "failed to list FAQ chunks") {
	if errors.Is(err, context.DeadlineExceeded) {
		// large KB: retry with a longer deadline
		ctx, cancel = context.WithTimeout(context.Background(), 5*time.Minute)
		defer cancel()
		data, err = svc.ExportFAQEntries(ctx, kbID, page, tagUUIDs, keyword, 0, "", "")
	}
}

When it happens

Trigger: Calling ExportFAQEntries(kbID) when ListAllFAQChunksForExport fails: DB connection error, query timeout scanning a very large FAQ knowledge, context cancellation, or a repository-level error (bad index, table lock).

Common situations: Exporting a huge FAQ knowledge base causing query timeouts; database maintenance/failover during export; context deadline from an HTTP gateway shorter than the export duration; missing DB indexes after schema changes.

Related errors

• failed to build tag map: %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/2a118ea1f93e9257. Report an issue: GitHub.