{"record":{"id":"dad346917a6c7165","repo":"infiniflow/ragflow","slug":"database-error-knowledgebase","errorCode":null,"errorMessage":"Database error (Knowledgebase)!","messagePattern":"Database error \\(Knowledgebase\\)!","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"api/db/services/document_service.py","lineNumber":458,"sourceCode":"        # maybe cause slow query by deep paginate, optimize later\n        offset, limit = 0, 100\n        res = []\n        while True:\n            doc_batch = docs.offset(offset).limit(limit)\n            _temp = list(doc_batch.dicts())\n            if not _temp:\n                break\n            res.extend(_temp)\n            offset += limit\n        return res\n\n    @classmethod\n    @DB.connection_context()\n    def insert(cls, doc):\n        if not cls.save(**doc):\n            raise RuntimeError(\"Database error (Document)!\")\n        if not KnowledgebaseService.atomic_increase_doc_num_by_id(doc[\"kb_id\"]):\n            raise RuntimeError(\"Database error (Knowledgebase)!\")\n        return Document(**doc)\n\n    @classmethod\n    @DB.connection_context()\n    def remove_document(cls, doc, tenant_id):\n        from api.db.services.task_service import TaskService, cancel_all_task_of\n\n        if not cls.delete_document_and_update_kb_counts(doc.id):\n            return True\n\n        chunk_index_name = search.index_name(tenant_id)\n        chunk_index_exists = settings.docStoreConn.index_exist(chunk_index_name, doc.kb_id)\n\n        # Cancel all running tasks first using preset function in task_service.py --- set cancel flag in Redis\n        try:\n            cancel_all_task_of(doc.id)\n            logging.info(f\"Cancelled all tasks for document {doc.id}\")\n        except Exception as e:","sourceCodeStart":440,"sourceCodeEnd":476,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/api/db/services/document_service.py#L440-L476","documentation":"RuntimeError raised right after a successful Document insert when KnowledgebaseService.atomic_increase_doc_num_by_id fails to bump the knowledge base's doc_num counter (conditional UPDATE affected 0 rows, typically because kb_id does not exist). Insert and counter are in one transaction so both roll back.","triggerScenarios":"DocumentService.insert with a kb_id that has no matching Knowledgebase row — deleted dataset, wrong tenant, or typo'd id — so the atomic UPDATE ... WHERE id=kb_id matches nothing.","commonSituations":"Document created against a dataset deleted concurrently; kb_id from another environment after config copy; race between dataset deletion and upload.","solutions":["Verify kb_id exists (KnowledgebaseService.get_by_id) before inserting the document.","Re-check for races: block uploads while the dataset is being deleted.","Confirm the tenant/context used for upload matches the dataset's owner."],"exampleFix":"# before\nDocumentService.insert({**doc, \"kb_id\": maybe_stale_kb_id})\n# after\nok, kb = KnowledgebaseService.get_by_id(kb_id)\nif not ok:\n    raise ValueError(f\"knowledgebase {kb_id} not found\")\nDocumentService.insert({**doc, \"kb_id\": kb_id})","handlingStrategy":"validation","validationCode":"from api.db.services.knowledgebase_service import KnowledgebaseService\nok, _kb = KnowledgebaseService.get_by_id(doc['kb_id'])\nif not ok:\n    raise ValueError(f\"knowledgebase {doc['kb_id']} does not exist; refusing to insert document\")","typeGuard":null,"tryCatchPattern":"try:\n    DocumentService.insert(doc)\nexcept RuntimeError as e:\n    if 'Database error (Knowledgebase)' in str(e):\n        # document row rolled back too; verify kb_id then resubmit with a valid one\n        verify_and_fix_kb(doc['kb_id'])","preventionTips":["Block uploads to a dataset while it is being deleted.","Treat this error as 'kb_id stale' first — check for concurrent dataset deletion."],"tags":["database","knowledge-base","document","foreign-key"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}