Improve error message when await_ call errors

Fixes: #5832
Change-Id: Ia2ed8f1d1ec54e5f6e1a8f817a69446fdb3b7f6d

2 files changed, 15 insertions, 4 deletions

diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py
index 08b1bb060..289b8dfab 100644
--- a/lib/sqlalchemy/exc.py
+++ b/lib/sqlalchemy/exc.py
@@ -294,6 +294,15 @@ class AwaitRequired(InvalidRequestError):
     code = "xd1r"
 
 
+class MissingGreenlet(InvalidRequestError):
+    r"""Error raised by the async greenlet await\_ if called while not inside
+    the greenlet spawn context.
+
+    """
+
+    code = "xd2s"
+
+
 class NoReferencedTableError(NoReferenceError):
     """Raised by ``ForeignKey`` when the referred ``Table`` cannot be
     located.
diff --git a/lib/sqlalchemy/util/_concurrency_py3k.py b/lib/sqlalchemy/util/_concurrency_py3k.py
index 663d3e0f4..8edd057ef 100644
--- a/lib/sqlalchemy/util/_concurrency_py3k.py
+++ b/lib/sqlalchemy/util/_concurrency_py3k.py
@@ -44,8 +44,9 @@ def await_only(awaitable: Coroutine) -> Any:
     # this is called in the context greenlet while running fn
     current = greenlet.getcurrent()
     if not isinstance(current, _AsyncIoGreenlet):
-        raise exc.InvalidRequestError(
-            "greenlet_spawn has not been called; can't call await_() here."
+        raise exc.MissingGreenlet(
+            "greenlet_spawn has not been called; can't call await_() here. "
+            "Was IO attempted in an unexpected place?"
         )
 
     # returns the control to the driver greenlet passing it
@@ -69,9 +70,10 @@ def await_fallback(awaitable: Coroutine) -> Any:
     if not isinstance(current, _AsyncIoGreenlet):
         loop = asyncio.get_event_loop()
         if loop.is_running():
-            raise exc.InvalidRequestError(
+            raise exc.MissingGreenlet(
                 "greenlet_spawn has not been called and asyncio event "
-                "loop is already running; can't call await_() here."
+                "loop is already running; can't call await_() here. "
+                "Was IO attempted in an unexpected place?"
             )
         return loop.run_until_complete(awaitable)