diff --git a/docs/source/api.rst b/docs/source/api.rst
index 82f7241c5..423da33e9 100644
--- a/docs/source/api.rst
+++ b/docs/source/api.rst
@@ -273,6 +273,15 @@ Closing a driver will immediately shut down all connections in the pool.
                 The transformer function must **not** return the
                 :class:`neo4j.Result` itself.
 
+
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.Result` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 
diff --git a/docs/source/async_api.rst b/docs/source/async_api.rst
index 08e0b3d22..ff0749e99 100644
--- a/docs/source/async_api.rst
+++ b/docs/source/async_api.rst
@@ -255,6 +255,14 @@ Closing a driver will immediately shut down all connections in the pool.
                 The transformer function must **not** return the
                 :class:`neo4j.AsyncResult` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.AsyncResult` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 
diff --git a/src/neo4j/_async/driver.py b/src/neo4j/_async/driver.py
index 06027c01f..472e6e07a 100644
--- a/src/neo4j/_async/driver.py
+++ b/src/neo4j/_async/driver.py
@@ -686,6 +686,14 @@ async def example(driver: neo4j.AsyncDriver) -> int:
                 The transformer function must **not** return the
                 :class:`neo4j.AsyncResult` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.AsyncResult` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::
 
diff --git a/src/neo4j/_sync/driver.py b/src/neo4j/_sync/driver.py
index 9bc994e55..d3a3e69d4 100644
--- a/src/neo4j/_sync/driver.py
+++ b/src/neo4j/_sync/driver.py
@@ -684,6 +684,14 @@ def example(driver: neo4j.Driver) -> int:
                 The transformer function must **not** return the
                 :class:`neo4j.Result` itself.
 
+            .. warning::
+
+                N.B. the driver might retry the underlying transaction so the
+                transformer might get invoked more than once (with different
+                :class:`neo4j.Result` objects).
+                Therefore, it needs to be idempotent (i.e., have the same
+                effect, regardless if called once or many times).
+
             Example transformer that checks that exactly one record is in the
             result stream, then returns the record and the result summary::