backend/app/core/kb_conversion_service.py

@@ -498,9 +498,25 @@ async def convert_document(
         await db.flush()
         return []
 
-    # Persist nodes
-    for node in nodes:
-        db.add(node)
+    # Persist nodes — insert roots first to satisfy parent_node_id FK,
+    # then children in subsequent passes until all are inserted.
+    remaining = list(nodes)
+    inserted_ids: set[Any] = set()
+    while remaining:
+        batch = [
+            n for n in remaining
+            if n.parent_node_id is None or n.parent_node_id in inserted_ids
+        ]
+        if not batch:
+            # Circular reference or orphan — force insert remaining to surface the real error
+            for n in remaining:
+                db.add(n)
+            break
+        for n in batch:
+            db.add(n)
+            inserted_ids.add(n.id)
+        await db.flush()
+        remaining = [n for n in remaining if n.id not in inserted_ids]
 
     # Update import record
     elapsed_ms = int((time.monotonic() - start_time) * 1000)