diff --git a/docs/api/baseplate/clients/sqlalchemy.rst b/docs/api/baseplate/clients/sqlalchemy.rst
index 5fdfe38b7..ca025475e 100644
--- a/docs/api/baseplate/clients/sqlalchemy.rst
+++ b/docs/api/baseplate/clients/sqlalchemy.rst
@@ -52,6 +52,14 @@ request::
 Configuration
 -------------
 
+.. warning::
+
+   :py:class:`sqlalchemy.pool.QueuePool` does not handle `ServerTimeout`
+   exceptions gracefully, potentially leaking connections. It is recommended
+   to avoid local pooling entirely (via :py:class:`sqlalchemy.pool.NullPool`)
+   while this issue persists and instead rely on middleware pooling (such as
+   `pgbouncer`).
+
 .. autoclass:: SQLAlchemySession
 
 .. autofunction:: engine_from_config
diff --git a/docs/api/baseplate/observers/timeout.rst b/docs/api/baseplate/observers/timeout.rst
index dafe25ea8..7ca1e1081 100644
--- a/docs/api/baseplate/observers/timeout.rst
+++ b/docs/api/baseplate/observers/timeout.rst
@@ -14,6 +14,14 @@ upstream services are yet taken into account.
    taking a long time because it is doing compute-heavy actions and not
    yielding to the event loop it might go on longer than the allotted timeout.
 
+.. warning::
+
+   The timeout mechanism may throw a `ServerTimeout` exception whenever a gevent
+   context switch occurs. If this exception is not handled gracefully your
+   application could get stuck in a bad state. For example, if a `ServerTimeout`
+   exception is thrown while releasing a connection then the connection might
+   never be fully released.
+
 .. versionadded:: 1.2
 
 .. versionchanged:: 1.3.3