diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala b/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
index ed417609cf..0598ba0c81 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
@@ -154,6 +154,9 @@ class Flow[-In, +Out, +Mat](delegate: scaladsl.Flow[In, Out, Mat]) extends Graph
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned list MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: japi.Function[Out, java.util.List[T]]): javadsl.Flow[In, T, Mat] =
     new Flow(delegate.mapConcat(elem ⇒ Util.immutableSeq(f.apply(elem))))
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala b/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
index 21e7d114c5..688752d060 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/Source.scala
@@ -292,6 +292,9 @@ class Source[+Out, +Mat](delegate: scaladsl.Source[Out, Mat]) extends Graph[Sour
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned list MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: japi.Function[Out, java.util.List[T]]): javadsl.Source[T, Mat] =
     new Source(delegate.mapConcat(elem ⇒ Util.immutableSeq(f.apply(elem))))
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
index f8badfa779..a6911b35f9 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
@@ -336,6 +336,9 @@ trait FlowOps[+Out, +Mat] {
   /**
    * Transform each input element into a sequence of output elements that is
    * then flattened into the output stream.
+   *
+   * The returned sequence MUST NOT contain `null` values,
+   * as they are illegal as stream elements - according to the Reactive Streams specification.
    */
   def mapConcat[T](f: Out ⇒ immutable.Seq[T]): Repr[T, Mat] = andThen(MapConcat(f.asInstanceOf[Any ⇒ immutable.Seq[Any]]))