RDBC-1021: raise InvalidOperationException when includes are used in a no_tracking session

session.load(..., includes=...) and query._include() silently discarded includes
when no_tracking=True, giving callers a false sense of correctness.
C# raises InvalidOperationException with "Cannot register includes when NoTracking
is enabled." Added the same guard to both the load() path and the query _include()
method, using the full C# exception message.

Regression test: test_no_tracking_includes_guard.py verifies that include calls raise
InvalidOperationException on no-tracking sessions for load, query, and document_query paths.

Author: redknightlois

ravendb/documents/session/document_session.py

@@ -316,6 +316,13 @@ def load(
             result = load_operation.get_documents(object_type)
             return result.popitem()[1] if len(result) == 1 else result if result else None
 
+        if self.no_tracking:
+            raise InvalidOperationException(
+                "Cannot register includes when NoTracking is enabled. "
+                "Included documents are not tracked, so subsequent Load operations for that data will still trigger additional server requests. "
+                "To avoid confusion, 'Include' operations are disallowed when tracking is disabled on the session or query."
+            )
+
         include_builder = IncludeBuilder(self.conventions)
         includes(include_builder)
 

ravendb/documents/session/query.py

@@ -52,6 +52,7 @@
     SuggestionBuilder,
 )
 from ravendb.documents.queries.utils import QueryFieldUtil
+from ravendb.exceptions.exceptions import InvalidOperationException
 from ravendb.documents.session.event_args import BeforeQueryEventArgs
 from ravendb.documents.session.loaders.include import IncludeBuilderBase, QueryIncludeBuilder
 from ravendb.documents.session.misc import MethodCall, CmpXchg, OrderingType, DocumentQueryCustomization
@@ -368,6 +369,12 @@ def __action():
         return MoreLikeThisScope(token, self.__add_query_parameter, __action)
 
     def _include(self, path_or_include_builder: Union[str, IncludeBuilderBase]) -> None:
+        if self._the_session is not None and self._the_session.no_tracking:
+            raise InvalidOperationException(
+                "Cannot register includes when NoTracking is enabled. "
+                "Included documents are not tracked, so subsequent Load operations for that data will still trigger additional server requests. "
+                "To avoid confusion, 'Include' operations are disallowed when tracking is disabled on the session or query."
+            )
         if isinstance(path_or_include_builder, str):
             self._document_includes.add(path_or_include_builder)
         elif isinstance(path_or_include_builder, IncludeBuilderBase):

ravendb/tests/jvm_migrated_tests/issues_tests/test_ravenDB_11217.py

@@ -37,7 +37,7 @@ def test_session_wide_no_tracking_should_work(self):
         with self.store.open_session(session_options=no_tracking_options) as session:
             self.assertEqual(0, session.advanced.number_of_requests)
 
-            product1 = session.load("products/1-A", Product, lambda b: b.include_documents("supplier"))
+            product1 = session.load("products/1-A", Product)
 
             self.assertEqual(1, session.advanced.number_of_requests)
 
@@ -52,7 +52,7 @@ def test_session_wide_no_tracking_should_work(self):
             self.assertEqual(2, session.advanced.number_of_requests)
             self.assertFalse(session.advanced.is_loaded(supplier.Id))
 
-            product2 = session.load("products/1-A", Product, lambda b: b.include_documents(("supplier")))
+            product2 = session.load("products/1-A", Product)
             self.assertNotEqual(product2, product1)
 
         with self.store.open_session(session_options=no_tracking_options) as session:
@@ -79,7 +79,7 @@ def test_session_wide_no_tracking_should_work(self):
 
         with self.store.open_session(session_options=no_tracking_options) as session:
             self.assertEqual(0, session.advanced.number_of_requests)
-            products = list(session.query(object_type=Product).include("supplier"))
+            products = list(session.query(object_type=Product))
 
             self.assertEqual(1, session.advanced.number_of_requests)
             self.assertEqual(1, len(products))
@@ -95,7 +95,7 @@ def test_session_wide_no_tracking_should_work(self):
             self.assertEqual(2, session.advanced.number_of_requests)
             self.assertFalse(session.advanced.is_loaded(supplier.Id))
 
-            products = list(session.query(object_type=Product).include("supplier"))
+            products = list(session.query(object_type=Product))
             self.assertEqual(1, len(products))
 
             product2 = products[0]

ravendb/tests/session_tests/test_no_tracking_includes_guard.py

@@ -0,0 +1,69 @@
+"""
+No-tracking session: using includes raises when session.no_tracking is True.
+
+C# reference: SlowTests/Issues/RavenDB_21339.cs
+  Using_Includes_In_Non_Tracking_Session_Should_Throw
+"""
+
+from ravendb.documents.session.misc import SessionOptions
+from ravendb.tests.test_base import TestBase
+
+
+class Manager:
+    def __init__(self, name: str = None):
+        self.name = name
+
+
+class Employee:
+    def __init__(self, name: str = None, manager_id: str = None):
+        self.name = name
+        self.manager_id = manager_id
+
+
+class TestRavenDB21339(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def _populate(self):
+        with self.store.open_session() as session:
+            session.store(Manager(name="Boss"), "managers/1")
+            session.store(Employee(name="Alice", manager_id="managers/1"), "employees/1")
+            session.save_changes()
+
+    def test_load_with_includes_in_no_tracking_session_should_throw(self):
+        """
+        session.load() with an include builder in a no_tracking session must
+        raise an exception, not silently ignore the includes."""
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                session.load(
+                    "employees/1",
+                    Employee,
+                    includes=lambda b: b.include_documents("manager_id"),
+                )
+            self.assertIn("Cannot register includes when NoTracking is enabled", str(ctx.exception))
+
+    def test_query_with_include_in_no_tracking_session_should_throw(self):
+        """
+        query.include() in a no_tracking session must raise an exception,
+        not silently add the include to an unused tracking cache."""
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                list(session.query(object_type=Employee).include("manager_id").wait_for_non_stale_results())
+            self.assertIn("Cannot register includes when NoTracking is enabled", str(ctx.exception))
+
+    def test_document_query_with_include_in_no_tracking_session_should_throw(self):
+        """
+        C# spec: session.Advanced.DocumentQuery<Product>().Include(x => x.Supplier).ToList()
+        in a no_tracking session must raise InvalidOperationException.
+        """
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                list(session.advanced.document_query(object_type=Employee).include("manager_id"))
+            self.assertIn("Cannot register includes when NoTracking is enabled", str(ctx.exception))