{"record":{"id":"e5d87e94f6c8251c","repo":"infiniflow/ragflow","slug":"database-error-document-removal","errorCode":null,"errorMessage":"Database error (Document removal)!","messagePattern":"Database error \\(Document removal\\)!","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"api/db/services/file_service.py","lineNumber":724,"sourceCode":"        root_folder = FileService.get_root_folder(tenant_id)\n        pf_id = root_folder[\"id\"]\n        FileService.init_knowledgebase_docs(pf_id, tenant_id)\n        errors = \"\"\n        kb_table_num_map = {}\n        for doc_id in doc_ids:\n            try:\n                e, doc = DocumentService.get_by_id(doc_id)\n                if not e:\n                    raise RuntimeError(\"document not found\")\n                tenant_id = DocumentService.get_tenant_id(doc_id)\n                if not tenant_id:\n                    raise RuntimeError(\"Tenant not found!\")\n\n                b, n = File2DocumentService.get_storage_address(doc_id=doc_id)\n\n                TaskService.filter_delete([Task.doc_id == doc_id])\n                if not DocumentService.remove_document(doc, tenant_id):\n                    raise RuntimeError(\"Database error (Document removal)!\")\n\n                f2d = File2DocumentService.get_by_document_id(doc_id)\n                deleted_file_count = 0\n                if f2d:\n                    deleted_file_count = FileService.filter_delete([File.source_type == FileSource.KNOWLEDGEBASE, File.id == f2d[0].file_id])\n                File2DocumentService.delete_by_document_id(doc_id)\n                if deleted_file_count > 0:\n                    settings.STORAGE_IMPL.rm(b, n)\n\n                doc_parser = doc.parser_id\n                if doc_parser == ParserType.TABLE:\n                    kb_id = doc.kb_id\n                    if kb_id not in kb_table_num_map:\n                        counts = DocumentService.count_by_kb_id(kb_id=kb_id, keywords=\"\", run_status=[TaskStatus.DONE], types=[])\n                        kb_table_num_map[kb_id] = counts\n                    kb_table_num_map[kb_id] -= 1\n                    if kb_table_num_map[kb_id] <= 0:\n                        KnowledgebaseService.delete_field_map(kb_id)","sourceCodeStart":706,"sourceCodeEnd":742,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/api/db/services/file_service.py#L706-L742","documentation":"Raised in FileService.delete_docs when DocumentService.remove_document(doc, tenant_id) returns falsy, i.e. the document record (and its chunks/related rows) could not be removed by the service layer. Task rows for the doc were already filter-deleted, so state may be partially cleaned.","triggerScenarios":"remove_document failing on a DB error or on chunk/index cleanup; deleting a document whose task records are being written by a running parse job; connection issues mid-delete.","commonSituations":"Deleting a document while it is being parsed or indexed; long-running removal hitting statement timeouts; DB under heavy load.","solutions":["Check server logs for the failure inside remove_document (the underlying error is logged there).","Ensure no parse/index task is running for the document (stop tasks, then delete).","Retry the deletion once the load drops.","If it persistently fails, inspect task and document-chunk tables for locks or orphans referencing the doc."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"running = TaskService.query(doc_id=doc_id, status=TaskStatus.RUNNING)\nif running:\n    cancel_tasks_then_wait(doc_id)","typeGuard":null,"tryCatchPattern":"for attempt in range(2):\n    errors, _ = FileService.delete_docs([doc_id], tenant_id)\n    if 'Document removal' not in errors:\n        break\n    time.sleep(2)","preventionTips":["Stop running parse/index tasks for a document before deleting it.","Delete during low DB load for very large documents.","Investigate repeated failures in logs rather than endlessly retrying — chunk tables may be locked."],"tags":["database","delete","document","concurrency","partial-state"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}