infiniflow/ragflow · critical · RuntimeError

Database error (File)!

Error message

Database error (File)!

What it means

RuntimeError from File2DocumentService.insert when saving the link row fails (cls.save returns falsy). Mirrors the Document insert guard: schema/constraint violations on the File2Document join table surface here and roll back the transaction.

Source

Thrown at api/db/services/file2document_service.py:51

        return list(objs)

    @classmethod
    @DB.connection_context()
    def get_by_document_id(cls, document_id):
        objs = cls.model.select().where(cls.model.document_id == document_id)
        return list(objs)

    @classmethod
    @DB.connection_context()
    def get_by_document_ids(cls, document_ids):
        objs = cls.model.select().where(cls.model.document_id.in_(document_ids))
        return list(objs.dicts())

    @classmethod
    @DB.connection_context()
    def insert(cls, obj):
        if not cls.save(**obj):
            raise RuntimeError("Database error (File)!")
        return File2Document(**obj)

    @classmethod
    @DB.connection_context()
    def delete_by_file_id(cls, file_id):
        return cls.model.delete().where(cls.model.file_id == file_id).execute()

    @classmethod
    @DB.connection_context()
    def delete_by_document_ids_or_file_ids(cls, document_ids, file_ids):
        if not document_ids:
            return cls.model.delete().where(cls.model.file_id.in_(file_ids)).execute()
        elif not file_ids:
            return cls.model.delete().where(cls.model.document_id.in_(document_ids)).execute()
        return cls.model.delete().where(cls.model.document_id.in_(document_ids) | cls.model.file_id.in_(file_ids)).execute()

    @classmethod
    @DB.connection_context()

View on GitHub (pinned to 554fb1133a)

Solutions

  1. Validate that both file_id and document_id exist before inserting the association.
  2. Check for an existing link and update/skip instead of re-inserting.
  3. Restrict the dict to File2Document model fields.

Example fix

# before
File2DocumentService.insert({"file_id": f, "document_id": d})
# after
exists = File2DocumentService.get_by_file_id(f)
if not any(x["document_id"] == d for x in exists):
    File2DocumentService.insert({"id": get_uuid(), "file_id": f, "document_id": d})
Defensive patterns

Strategy: validation

Validate before calling

existing = File2DocumentService.get_by_document_ids([document_id])
if any(str(x.get('file_id')) == str(file_id) for x in existing):
    return  # link already present, skip insert
File2DocumentService.insert({"id": get_uuid(), "file_id": file_id, "document_id": document_id})

Try / catch

try:
    File2DocumentService.insert(obj)
except RuntimeError as e:
    if 'Database error (File)' in str(e):
        # verify both endpoints exist, fix obj fields, then retry once
        verify_file_and_document(obj)

Prevention

When it happens

Trigger: Creating a file-document association with invalid field values — nonexistent file_id or document_id, duplicate pair, or fields not on the model.

Common situations: Linking a document to a file after the file row was deleted; retrying an insert for a pair already linked; passing extra keys not in the model.

Related errors

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