Tencent/WeKnora · error

failed to create chunk: %w

Error message

failed to create chunk: %w

What it means

CreateFAQEntry wraps failures from chunkService.CreateChunks, which persists the FAQ chunk to the database with status Stored. The chunk could not be written, so the entry creation fails before indexing. Typical wrapped causes are DB connectivity errors, constraint violations (e.g. duplicate SeqID when migrating with an explicit payload.ID), or context cancellation.

Source

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

		Content:         buildFAQChunkContent(meta, indexMode),
		IsEnabled:       isEnabled,
		Flags:           flags,
		ChunkType:       types.ChunkTypeFAQ,
		TagID:           tagID, // 使用解析后的 TagID
		Status:          int(types.ChunkStatusStored),
	}
	// 如果指定了 ID（用于数据迁移），设置 SeqID
	if payload.ID != nil && *payload.ID > 0 {
		chunk.SeqID = *payload.ID
	}

	if err := chunk.SetFAQMetadata(meta); err != nil {
		return nil, fmt.Errorf("failed to set FAQ metadata: %w", err)
	}

	// 保存chunk
	if err := s.chunkService.CreateChunks(ctx, []*types.Chunk{chunk}); err != nil {
		return nil, fmt.Errorf("failed to create chunk: %w", err)
	}

	// 索引chunk：交互式创建给索引步骤设硬上限，避免 embedding 抖动把请求拖长
	indexCtx, cancelIndex := context.WithTimeout(ctx, faqCreateIndexBudget)
	indexErr := s.indexFAQChunks(indexCtx, kb, faqKnowledge, []*types.Chunk{chunk}, embeddingModel, true, false)
	cancelIndex()
	if indexErr != nil {
		// 如果索引失败，删除已创建的chunk。回滚失败会留下一条 stored 状态的
		// 残留：它不出现在列表里，却会被重复校验命中，因此必须告警而非静默。
		if delErr := s.chunkService.DeleteChunk(ctx, chunk.ID); delErr != nil {
			logger.Errorf(ctx,
				"CreateFAQEntry: rollback failed, chunk %s left in stored state: %v", chunk.ID, delErr)
		}
		return nil, fmt.Errorf("failed to index chunk: %w", indexErr)
	}

	// 更新chunk状态为已索引
	chunk.Status = int(types.ChunkStatusIndexed)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Check the wrapped DB error in logs; fix connectivity or constraint issues and retry.
2. If migrating with payload.ID, ensure the SeqID is not already used in the target KB (drop or re-map conflicting IDs).
3. Increase client timeout so the context is not cancelled before persistence completes.
4. Verify DB migrations/schema constraints are current and no unique index blocks the insert.

Example fix

// before: migration reuses an existing SeqID
payload := &types.FAQEntryPayload{ID: int64Ptr(42)}
// after: probe for an existing chunk with that SeqID first
if exists, _ := chunkRepo.SeqIDExists(ctx, tenantID, kbID, 42); exists {
	payload.ID = nil // let the system allocate a new SeqID
}

// before migration creates, ensure the explicit SeqID is free
if payload.ID != nil && *payload.ID > 0 {
	exists, err := chunkRepo.SeqIDExists(ctx, tenantID, kbID, *payload.ID)
	if err != nil || exists {
		return errors.New("SeqID already used in target KB; remap before import")
	}
}

entry, err := svc.CreateFAQEntry(ctx, kbID, payload)
if err != nil && strings.Contains(err.Error(), "failed to create chunk") {
	if ctx.Err() != nil {
		return nil, errors.New("request context expired during persistence; increase timeout and retry")
	}
	return nil, fmt.Errorf("chunk persistence failed (check DB health/constraints): %w", err)
}

When it happens

Trigger: Calling CreateFAQEntry when the DB insert for the chunk fails: connection loss, transaction deadlock, duplicate primary key/SeqID (payload.ID set to an already-used ID during data migration), or request context cancelled/expired before the write completes.

Common situations: Database outage or pool exhaustion under load; import/migration jobs reusing existing SeqIDs; client timeouts cancelling the request context mid-write; schema constraint changes after upgrade.

Related errors

• failed to ensure FAQ knowledge: %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/227e2e053d54aa76. Report an issue: GitHub.