diff --git a/docs/classes.rst b/docs/classes.rst
index 4f2167dac1d..82145a9a8b4 100644
--- a/docs/classes.rst
+++ b/docs/classes.rst
@@ -58,6 +58,17 @@ interactive Python session demonstrating this example is shown below:
     Static member functions can be bound in the same way using
     :func:`class_::def_static`.
 
+.. note::
+
+    By default pybind11 uses a custom metaclass which is known to be
+    incompatible with
+    `abc.ABCMeta <https://docs.python.org/3/library/abc.html#abc.ABCMeta>`_
+    and can also lead to other surprising issues. In such cases,
+    using ``py::metaclass(PyType_Type)`` is often a good solution.
+    Please see
+    `#5015 <https://github.com/pybind/pybind11/pull/5015>`_
+    for more background.
+
 .. note::
 
     Binding C++ types in unnamed namespaces (also known as anonymous namespaces)