diff --git a/akka-docs/java/dispatchers.rst b/akka-docs/java/dispatchers.rst
index 2dcd5049c5..b7a16d9283 100644
--- a/akka-docs/java/dispatchers.rst
+++ b/akka-docs/java/dispatchers.rst
@@ -24,6 +24,10 @@ If you are starting to get contention on the single dispatcher (the ``Executor``
 for a dedicated dispatcher for better flexibility and configurability then you can override the defaults and define your own dispatcher.
 See below for details on which ones are available and how they can be configured.
 
+.. warning::
+  Try to stick to a sensible default dispatcher, that means avoid using CallingThreadDispatcher, BalancingDispatcher or PinnedDispatcher
+  as the default-dispatcher. This is because they have very specific requirements from the environment in which they are used.
+
 Setting the dispatcher
 ----------------------
 
diff --git a/akka-docs/scala/dispatchers.rst b/akka-docs/scala/dispatchers.rst
index 50807fbc55..94ae563e64 100644
--- a/akka-docs/scala/dispatchers.rst
+++ b/akka-docs/scala/dispatchers.rst
@@ -24,6 +24,10 @@ If you are starting to get contention on the single dispatcher (the ``Executor``
 for a dedicated dispatcher for better flexibility and configurability then you can override the defaults and define your own dispatcher.
 See below for details on which ones are available and how they can be configured.
 
+.. warning::
+  Try to stick to a sensible default dispatcher, that means avoid using CallingThreadDispatcher, BalancingDispatcher or PinnedDispatcher
+  as the default-dispatcher. This is because they have very specific requirements from the environment in which they are used.
+
 Setting the dispatcher
 ----------------------