What causes "Database error (Document removal)!" in infiniflow/ragflow?

Check server logs for the failure inside remove_document (the underlying error is logged there).

infiniflow/ragflow · error · RuntimeError

Database error (Document removal)!

Error message

Database error (Document removal)!

What it means

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.

Source

Thrown at api/db/services/file_service.py:724

        root_folder = FileService.get_root_folder(tenant_id)
        pf_id = root_folder["id"]
        FileService.init_knowledgebase_docs(pf_id, tenant_id)
        errors = ""
        kb_table_num_map = {}
        for doc_id in doc_ids:
            try:
                e, doc = DocumentService.get_by_id(doc_id)
                if not e:
                    raise RuntimeError("document not found")
                tenant_id = DocumentService.get_tenant_id(doc_id)
                if not tenant_id:
                    raise RuntimeError("Tenant not found!")

                b, n = File2DocumentService.get_storage_address(doc_id=doc_id)

                TaskService.filter_delete([Task.doc_id == doc_id])
                if not DocumentService.remove_document(doc, tenant_id):
                    raise RuntimeError("Database error (Document removal)!")

                f2d = File2DocumentService.get_by_document_id(doc_id)
                deleted_file_count = 0
                if f2d:
                    deleted_file_count = FileService.filter_delete([File.source_type == FileSource.KNOWLEDGEBASE, File.id == f2d[0].file_id])
                File2DocumentService.delete_by_document_id(doc_id)
                if deleted_file_count > 0:
                    settings.STORAGE_IMPL.rm(b, n)

                doc_parser = doc.parser_id
                if doc_parser == ParserType.TABLE:
                    kb_id = doc.kb_id
                    if kb_id not in kb_table_num_map:
                        counts = DocumentService.count_by_kb_id(kb_id=kb_id, keywords="", run_status=[TaskStatus.DONE], types=[])
                        kb_table_num_map[kb_id] = counts
                    kb_table_num_map[kb_id] -= 1
                    if kb_table_num_map[kb_id] <= 0:
                        KnowledgebaseService.delete_field_map(kb_id)

View on GitHub (pinned to 554fb1133a)

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.

Defensive patterns

Strategy: retry

Validate before calling

running = TaskService.query(doc_id=doc_id, status=TaskStatus.RUNNING)
if running:
    cancel_tasks_then_wait(doc_id)

Try / catch

for attempt in range(2):
    errors, _ = FileService.delete_docs([doc_id], tenant_id)
    if 'Document removal' not in errors:
        break
    time.sleep(2)

Prevention

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.

When it happens

Trigger: 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.

Common situations: Deleting a document while it is being parsed or indexed; long-running removal hitting statement timeouts; DB under heavy load.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/e5d87e94f6c8251c. Report an issue: GitHub.