diff --git a/akka-docs/java/transactors.rst b/akka-docs/java/transactors.rst
index 6795d8ba8d..f7471412a9 100644
--- a/akka-docs/java/transactors.rst
+++ b/akka-docs/java/transactors.rst
@@ -110,6 +110,14 @@ object, passing in an ``akka.transactor.Atomically`` object.
 The coordinated transaction will wait for the other transactions before
 committing. If any of the coordinated transactions fail then they all fail.
 
+.. note::
+
+   The same actor should not be added to a coordinated transaction more than
+   once. The transaction will not be able to complete as an actor only processes
+   a single message at a time. When processing the first message the coordinated
+   transaction will wait for the commit barrier, which in turn needs the second
+   message to be received to proceed.
+
 
 UntypedTransactor
 =================
diff --git a/akka-docs/scala/transactors.rst b/akka-docs/scala/transactors.rst
index 318523a513..84ed60d669 100644
--- a/akka-docs/scala/transactors.rst
+++ b/akka-docs/scala/transactors.rst
@@ -111,6 +111,14 @@ object:
 The coordinated transaction will wait for the other transactions before
 committing. If any of the coordinated transactions fail then they all fail.
 
+.. note::
+
+   The same actor should not be added to a coordinated transaction more than
+   once. The transaction will not be able to complete as an actor only processes
+   a single message at a time. When processing the first message the coordinated
+   transaction will wait for the commit barrier, which in turn needs the second
+   message to be received to proceed.
+
 
 Transactor
 ==========