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

Check the server log for the wrapped exception to see the true cause.

infiniflow/ragflow · error · RuntimeError

Database error (list_by_parent_id)!

Error message

Database error (list_by_parent_id)!

What it means

Raised by FileService.list_all_files_by_parent_id when the SELECT of children under a parent_id fails. The real exception is logged ('list_by_parent_id failed'); the RuntimeError is a generic wrapper for any DB-level failure during the query.

Source

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

                }
                DocumentService.insert(doc)

                FileService.add_file_from_kb(doc, kb_folder["id"], kb.tenant_id)
                files.append((doc, blob))
            except Exception as e:  # noqa: BLE001 - collect per-file errors and keep processing the rest
                err.append(file.filename + ": " + str(e))

        return err, files

    @classmethod
    @DB.connection_context()
    def list_all_files_by_parent_id(cls, parent_id):
        try:
            files = cls.model.select().where((cls.model.parent_id == parent_id) & (cls.model.id != parent_id))
            return list(files)
        except Exception:
            logger.exception("list_by_parent_id failed")
            raise RuntimeError("Database error (list_by_parent_id)!")

    @staticmethod
    def parse_docs(file_objs, user_id):
        with ThreadPoolExecutor(max_workers=12) as exe:
            threads = []
            for file in file_objs:
                threads.append(exe.submit(FileService.parse, file.filename, file.read(), False))

            res = []
            for th in threads:
                res.append(th.result())

        return "\n\n".join(res)

    @staticmethod
    def parse(filename, blob, img_base64=True, tenant_id=None, layout_recognize=None):
        from api.apps import current_user
        from rag.app import audio, email, naive, picture, presentation

View on GitHub (pinned to 554fb1133a)

Solutions

Check the server log for the wrapped exception to see the true cause.
Retry the listing after the concurrent write operation completes.
Verify DB connectivity and that the file table is intact (simple SELECT count(*) FROM file WHERE parent_id = ...).
If it recurs, examine rows for NULL or malformed id/parent_id values.

Defensive patterns

Strategy: retry

Try / catch

try:
    files = FileService.list_all_files_by_parent_id(parent_id)
except RuntimeError:
    logger.warning('listing failed, likely contention; retrying')
    files = FileService.list_all_files_by_parent_id(parent_id)

Prevention

Avoid listing a folder exactly while deleting or uploading into it.
Keep an eye on DB lock wait metrics if this recurs.
Use the returned error to trigger a UI refresh rather than showing raw errors.

When it happens

Trigger: Querying children of a folder while that subtree is being modified/deleted (lock contention), a dropped connection, or corrupted data causing the id != parent_id comparison to behave unexpectedly (e.g. NULL ids).

Common situations: Listing a folder during a large deletion or upload; database restart or failover mid-request; rare schema/data inconsistencies after manual edits.

Related errors

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