diff --git a/docs/plugin_hooks.rst b/docs/plugin_hooks.rst
index b687a6e770..6c2ad1e546 100644
--- a/docs/plugin_hooks.rst
+++ b/docs/plugin_hooks.rst
@@ -1150,6 +1150,9 @@ get_metadata(datasette, key, database, table)
 
 This hook is responsible for returning a dictionary corresponding to Datasette :ref:`metadata`. This function is passed the ``database``, ``table`` and ``key`` which were passed to the upstream internal request for metadata. Regardless, it is important to return a global metadata object, where ``"databases": []`` would be a top-level key. The dictionary returned here, will be merged with, and overwritten by, the contents of the physical ``metadata.yaml`` if one is present.
 
+.. warning::
+    The design of this plugin hook does not currently provide a mechanism for interacting with async code, and may change in the future. See `issue 1384 <https://github.com/simonw/datasette/issues/1384>`__.
+
 .. code-block:: python
 
     @hookimpl