Tencent/WeKnora · error

failed to ensure FAQ knowledge: %w

Error message

failed to ensure FAQ knowledge: %w

What it means

CreateFAQEntry wraps any failure from ensureFAQKnowledge, which finds or lazily creates the hidden internal Knowledge record that backs a FAQ knowledge base. It surfaces underlying DB errors (findFAQKnowledge query failure or CreateKnowledge insert failure) with this prefix. It means the FAQ container knowledge could not be located or created, so no entry can be stored.

Source

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

	}

	// 同一标准问的并发创建必须串行：下面的重复校验只看得到已落库的条目，
	// 拦不住还在索引中的兄弟请求（上游超时重试就会造出这种并发）。
	releaseGuard, err := s.acquireFAQCreateGuard(ctx, tenantID, kb.ID, meta.StandardQuestion)
	if err != nil {
		return nil, err
	}
	defer releaseGuard()

	// 检查标准问和相似问是否与其他条目重复
	if err := s.checkFAQQuestionDuplicate(ctx, tenantID, kb.ID, "", meta); err != nil {
		return nil, err
	}

	// 确保FAQ Knowledge存在
	faqKnowledge, err := s.ensureFAQKnowledge(ctx, tenantID, kb)
	if err != nil {
		return nil, fmt.Errorf("failed to ensure FAQ knowledge: %w", err)
	}

	// 获取索引模式
	indexMode := types.FAQIndexModeQuestionOnly
	if kb.FAQConfig != nil && kb.FAQConfig.IndexMode != "" {
		indexMode = kb.FAQConfig.IndexMode
	}

	// 获取embedding模型
	embeddingModel, err := s.modelService.GetEmbeddingModel(ctx, kb.EmbeddingModelID)
	if err != nil {
		return nil, fmt.Errorf("failed to get embedding model: %w", err)
	}

	// 创建chunk
	isEnabled := true
	if payload.IsEnabled != nil {
		isEnabled = *payload.IsEnabled

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check database connectivity/health and retry CreateFAQEntry; this is usually a transient DB error surfaced by the wrapped cause.
2. Inspect the wrapped cause (%w) in logs to distinguish lookup failure vs insert failure and fix accordingly (e.g. resolve unique-constraint conflict).
3. Avoid firing concurrent CreateFAQEntry calls against a brand-new FAQ knowledge base before the implicit FAQ knowledge row exists; serialize creation or pre-create the knowledge.
4. Verify schema/migrations are up to date for the knowledge table.

Example fix

// before
faqKnowledge, err := s.ensureFAQKnowledge(ctx, tenantID, kb)
if err != nil {
	return nil, fmt.Errorf("failed to ensure FAQ knowledge: %w", err)
}
// after (caller-side retry for transient DB errors)
entry, err := svc.CreateFAQEntry(ctx, kbID, payload)
if err != nil && isTransientDBError(err) {
	time.Sleep(backoff)
	entry, err = svc.CreateFAQEntry(ctx, kbID, payload)
}

// pre-check DB reachability and KB validity before creating
if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("database unavailable, postpone FAQ create: %w", err)
}
if _, err := svc.GetKnowledgeBase(ctx, kbID); err != nil {
	return fmt.Errorf("KB invalid: %w", err)
}

entry, err := svc.CreateFAQEntry(ctx, kbID, payload)
if err != nil && strings.Contains(err.Error(), "failed to ensure FAQ knowledge") {
	// transient DB problem: back off and retry once
	time.Sleep(2 * time.Second)
	entry, err = svc.CreateFAQEntry(ctx, kbID, payload)
}

When it happens

Trigger: Calling CreateFAQEntry on a valid FAQ knowledge base when the internal FAQ knowledge lookup/creation fails: database connectivity loss, deadlock or unique-key race between two concurrent creates both trying to insert the implicit FAQ knowledge row, or a repository timeout.

Common situations: Database under heavy load or during failover; two requests racing to create the implicit FAQ knowledge for a freshly created KB; misconfigured DB credentials/pool exhaustion causing connection errors; schema migration drift where the knowledge table is missing or locked.

Related errors

• failed to create chunk: %w
• failed to update chunk status: %w
• failed to get embedding model: %w
• failed to set FAQ metadata: %w
• failed to index chunk: %w

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