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

Inspect the doc dict: only model fields, all required columns set, valid types.

infiniflow/ragflow · critical · RuntimeError

Database error (Document)!

Error message

Database error (Document)!

What it means

RuntimeError from DocumentService.insert when cls.save(**doc) returns falsy — Peewee failed to persist the new Document row (constraint violation, invalid field, or DB error swallowed into a False result). It marks the transaction for rollback inside the connection_context decorator.

Source

Thrown at api/db/services/document_service.py:456

        docs = cls.model.select(*fields).join(Knowledgebase, on=(Knowledgebase.id == cls.model.kb_id)).where(cls.model.created_by == creator_id)
        docs.order_by(cls.model.create_time.asc())
        # maybe cause slow query by deep paginate, optimize later
        offset, limit = 0, 100
        res = []
        while True:
            doc_batch = docs.offset(offset).limit(limit)
            _temp = list(doc_batch.dicts())
            if not _temp:
                break
            res.extend(_temp)
            offset += limit
        return res

    @classmethod
    @DB.connection_context()
    def insert(cls, doc):
        if not cls.save(**doc):
            raise RuntimeError("Database error (Document)!")
        if not KnowledgebaseService.atomic_increase_doc_num_by_id(doc["kb_id"]):
            raise RuntimeError("Database error (Knowledgebase)!")
        return Document(**doc)

    @classmethod
    @DB.connection_context()
    def remove_document(cls, doc, tenant_id):
        from api.db.services.task_service import TaskService, cancel_all_task_of

        if not cls.delete_document_and_update_kb_counts(doc.id):
            return True

        chunk_index_name = search.index_name(tenant_id)
        chunk_index_exists = settings.docStoreConn.index_exist(chunk_index_name, doc.kb_id)

        # Cancel all running tasks first using preset function in task_service.py --- set cancel flag in Redis
        try:
            cancel_all_task_of(doc.id)

View on GitHub (pinned to 554fb1133a)

Solutions

Inspect the doc dict: only model fields, all required columns set, valid types.
Enable SQL logging (Peewee debug / service logs) to see the underlying INSERT error.
Verify DB schema matches the model (run migrations) and the connection is healthy.

Example fix

# before
doc = {"id": uid, "kb_id": kb_id, "name": name}  # missing other required columns
# after: build the full field set the model expects
from api.db.services.document_service import DocumentService
doc = {"id": get_uuid(), "kb_id": kb_id, "name": name, "parser_id": parser_id, "type": filetype, "created_by": tenant_id, "size": size, "status": "1"}

Defensive patterns

Strategy: try-catch

Validate before calling

fields = DocumentService.get_cls_model_fields()
extra = set(doc) - set(fields)
required_missing = {'kb_id', 'name'} - set(doc)
if extra or required_missing:
    raise ValueError(f'bad document fields: extra={extra}, missing={required_missing}')

Try / catch

try:
    DocumentService.insert(doc)
except RuntimeError as e:
    if 'Database error (Document)' in str(e):
        log_with_payload('document insert failed', doc)  # inspect Peewee logs, fix fields, do NOT blind-retry
    raise

Prevention

Log the full doc dict when this fires — the cause is almost always a field mismatch.
Build documents through one factory that mirrors the model's columns.

When it happens

Trigger: Creating a document with a dict that violates the Document schema: unknown/missing required fields, duplicate id, or a DB-level constraint; the save() helper returns 0 rows affected and the guard fires.

Common situations: Passing fields not on the model; NULL in a non-nullable column (e.g. kb_id); DB connection issues or schema drift after a migration; oversized values for varchar columns.

Related errors

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