{"record":{"id":"227e2e053d54aa76","repo":"Tencent/WeKnora","slug":"failed-to-create-chunk-w","errorCode":null,"errorMessage":"failed to create chunk: %w","messagePattern":"failed to create chunk: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/knowledge_faq.go","lineNumber":229,"sourceCode":"\t\tContent:         buildFAQChunkContent(meta, indexMode),\n\t\tIsEnabled:       isEnabled,\n\t\tFlags:           flags,\n\t\tChunkType:       types.ChunkTypeFAQ,\n\t\tTagID:           tagID, // 使用解析后的 TagID\n\t\tStatus:          int(types.ChunkStatusStored),\n\t}\n\t// 如果指定了 ID（用于数据迁移），设置 SeqID\n\tif payload.ID != nil && *payload.ID > 0 {\n\t\tchunk.SeqID = *payload.ID\n\t}\n\n\tif err := chunk.SetFAQMetadata(meta); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to set FAQ metadata: %w\", err)\n\t}\n\n\t// 保存chunk\n\tif err := s.chunkService.CreateChunks(ctx, []*types.Chunk{chunk}); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to create chunk: %w\", err)\n\t}\n\n\t// 索引chunk：交互式创建给索引步骤设硬上限，避免 embedding 抖动把请求拖长\n\tindexCtx, cancelIndex := context.WithTimeout(ctx, faqCreateIndexBudget)\n\tindexErr := s.indexFAQChunks(indexCtx, kb, faqKnowledge, []*types.Chunk{chunk}, embeddingModel, true, false)\n\tcancelIndex()\n\tif indexErr != nil {\n\t\t// 如果索引失败，删除已创建的chunk。回滚失败会留下一条 stored 状态的\n\t\t// 残留：它不出现在列表里，却会被重复校验命中，因此必须告警而非静默。\n\t\tif delErr := s.chunkService.DeleteChunk(ctx, chunk.ID); delErr != nil {\n\t\t\tlogger.Errorf(ctx,\n\t\t\t\t\"CreateFAQEntry: rollback failed, chunk %s left in stored state: %v\", chunk.ID, delErr)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"failed to index chunk: %w\", indexErr)\n\t}\n\n\t// 更新chunk状态为已索引\n\tchunk.Status = int(types.ChunkStatusIndexed)","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/knowledge_faq.go#L211-L247","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the wrapped DB error in logs; fix connectivity or constraint issues and retry.","If migrating with payload.ID, ensure the SeqID is not already used in the target KB (drop or re-map conflicting IDs).","Increase client timeout so the context is not cancelled before persistence completes.","Verify DB migrations/schema constraints are current and no unique index blocks the insert."],"exampleFix":"// before: migration reuses an existing SeqID\npayload := &types.FAQEntryPayload{ID: int64Ptr(42)}\n// after: probe for an existing chunk with that SeqID first\nif exists, _ := chunkRepo.SeqIDExists(ctx, tenantID, kbID, 42); exists {\n\tpayload.ID = nil // let the system allocate a new SeqID\n}","handlingStrategy":"validation","validationCode":"// before migration creates, ensure the explicit SeqID is free\nif payload.ID != nil && *payload.ID > 0 {\n\texists, err := chunkRepo.SeqIDExists(ctx, tenantID, kbID, *payload.ID)\n\tif err != nil || exists {\n\t\treturn errors.New(\"SeqID already used in target KB; remap before import\")\n\t}\n}","typeGuard":null,"tryCatchPattern":"entry, err := svc.CreateFAQEntry(ctx, kbID, payload)\nif err != nil && strings.Contains(err.Error(), \"failed to create chunk\") {\n\tif ctx.Err() != nil {\n\t\treturn nil, errors.New(\"request context expired during persistence; increase timeout and retry\")\n\t}\n\treturn nil, fmt.Errorf(\"chunk persistence failed (check DB health/constraints): %w\", err)\n}","preventionTips":["Set client timeouts comfortably above the full create+index latency","During migration, remap conflicting SeqIDs instead of reusing them","Monitor DB connection-pool usage during import windows","Verify unique constraints/indexes before bulk FAQ imports"],"tags":["database","persistence","faq","go"],"backgroundTag":"chunk-persist-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}