diff --git a/docs/iostream.rst b/docs/iostream.rst
index a2933a8f..a5e3869e 100644
--- a/docs/iostream.rst
+++ b/docs/iostream.rst
@@ -43,3 +43,8 @@
 
    .. autoclass:: PipeIOStream
       :members:
+
+   Exceptions
+   ----------
+
+   .. autoexception:: StreamClosedError
diff --git a/docs/releases/next.rst b/docs/releases/next.rst
index 05ea57d6..a8d384b9 100644
--- a/docs/releases/next.rst
+++ b/docs/releases/next.rst
@@ -229,6 +229,9 @@ Multiple modules
 `tornado.websocket`
 ~~~~~~~~~~~~~~~~~~~
 
+* `.WebSocketHandler` now catches `.StreamClosedError` and runs
+  `~.WebSocketHandler.on_close` immediately instead of logging a
+  stack trace.
 * New method `.WebSocketHandler.set_nodelay` can be used to set the
   ``TCP_NODELAY`` flag.
 
diff --git a/tornado/iostream.py b/tornado/iostream.py
index 9f9a1e60..079012c9 100644
--- a/tornado/iostream.py
+++ b/tornado/iostream.py
@@ -48,6 +48,12 @@ except ImportError:
 
 
 class StreamClosedError(IOError):
+    """Exception raised by `IOStream` methods when the stream is closed.
+
+    Note that the close callback is scheduled to run *after* other
+    callbacks on the stream (to allow for buffered data to be processed),
+    so you may see this error before you see the close callback.
+    """
     pass