diff --git a/agent/agent.h b/agent/agent.h
index 60b8990fdf9d6ea656326661c9b6e6747d457729..da59b45a8c9d750647f43f2505066c1bf98f1d2f 100644
--- a/agent/agent.h
+++ b/agent/agent.h
@@ -442,7 +442,10 @@ nice_agent_add_stream (
  * @agent: The #NiceAgent Object
  * @stream_id: The ID of the stream to remove
  *
- * Remove and free a previously created data stream from @agent
+ * Remove and free a previously created data stream from @agent. If any I/O
+ * streams have been created using nice_agent_get_io_stream(), they should be
+ * closed completely using g_io_stream_close() before this is called, or they
+ * will get broken pipe errors.
  *
  **/
 void
diff --git a/agent/iostream.c b/agent/iostream.c
index a3a5df3b05452159c562d7cf632df5fecdfdff73..f22ee4501df42bcde14492cbb5dde988379b88b7 100644
--- a/agent/iostream.c
+++ b/agent/iostream.c
@@ -53,7 +53,8 @@
  * If g_io_stream_close() is called on a #NiceIOStream, the I/O stream and
  * underlying #NiceAgent stream will be closed in both directions, but the
  * underlying stream will not be removed. Use nice_agent_remove_stream() to do
- * that.
+ * that, but only do so after g_io_stream_close() has completed, or the stream
+ * will return broken pipe errors.
  *
  * Since: 0.1.5
  */