diff --git a/akka-http-core/src/main/resources/reference.conf b/akka-http-core/src/main/resources/reference.conf
index 8840231ffc..5dfe6e340b 100644
--- a/akka-http-core/src/main/resources/reference.conf
+++ b/akka-http-core/src/main/resources/reference.conf
@@ -198,6 +198,13 @@ akka.http {
     # This value must be > 0.
     # (Note that, independently of this setting, pipelining will never be done
     # on a connection that still has a non-idempotent request in flight.
+    #
+    # Before increasing this value, make sure you understand the effects of head-of-line blocking.
+    # Using a connection pool, a request may be issued on a connection where a previous
+    # long-running request hasn't finished yet. The response to the pipelined requests may then be stuck
+    # behind the response of the long-running previous requests on the server. This may introduce an
+    # unwanted "coupling" of run time between otherwise unrelated requests.
+    #
     # See http://tools.ietf.org/html/rfc7230#section-6.3.2 for more info.)
     pipelining-limit = 1