Show warning about the use of _CachedStorage

Co-authored-by: Kenshin Abe <abe.kenshin@gmail.com>

docs/errors.rst

@@ -0,0 +1,24 @@
+Error Messages
+==============
+
+This section lists descriptions and background for common error messages and warnings raised or emitted by Optuna Dashboard.
+
+Warning Messages
+----------------
+
+Human-in-the-loop optimization will not work with ``_CachedStorage`` in Optuna prior to v3.2.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This warning occurs when the storage object associated with the Optuna Study is of the ``_CachedStorage`` class.
+
+When using ``RDBStorage`` with Optuna, it is implicitly wrapped with the ``_CachedStorage`` class for performance improvement.
+However, there is a bug in the ``_CachedStorage`` class that prevents Optuna from synchronizing the latest Trial information.
+This bug is not a problem for the general use case of Optuna, but it is critical for human-in-the-loop optimization.
+
+If you are using a version prior to v3.2, please upgrade to v3.2 or later, use another storage classes,
+or use a following dirty hack to unwrap ``_CachedStorage`` class.
+
+.. code-block:: python
+
+   if isinstance(study._storage, optuna.storages._CachedStorage):
+       study._storage = study._storage._backend

docs/index.rst

@@ -14,6 +14,7 @@ Real-time dashboard for `Optuna <https://github.com/optuna/optuna>`_.
 
    installation
    api
+   errors
 
 
 Links

optuna_dashboard/_form_widget.py

@@ -7,6 +7,8 @@ from typing import Union
 import warnings
 
 import optuna
+from optuna.version import __version__ as optuna_ver
+from packaging import version
 
 
 if TYPE_CHECKING:
@@ -195,6 +197,15 @@ def dict_to_form_widget(d: dict[str, Any]) -> ObjectiveFormWidget:
 def register_objective_form_widgets(
     study: optuna.Study, widgets: list[ObjectiveFormWidget]
 ) -> None:
+    if version.parse(optuna_ver) < version.Version("3.2") and isinstance(
+        study._storage, optuna.storages._CachedStorage
+    ):
+        warnings.warn(
+            "Human-in-the-loop optimization will not work with _CachedStorage in Optuna prior"
+            " to v3.2. See https://optuna-dashboard.readthedocs.io/en/latest/errors.html"
+            " for details."
+        )
+
     if len(study.directions) != len(widgets):
         raise ValueError("The length of actions must be the same with the number of objectives.")
     if any(
@@ -211,6 +222,15 @@ def register_objective_form_widgets(
 def register_user_attr_form_widgets(
     study: optuna.Study, widgets: list[ObjectiveFormWidget]
 ) -> None:
+    if version.parse(optuna_ver) < version.Version("3.2") and isinstance(
+        study._storage, optuna.storages._CachedStorage
+    ):
+        warnings.warn(
+            "Human-in-the-loop optimization will not work with _CachedStorage in Optuna prior"
+            " to v3.2. See https://optuna-dashboard.readthedocs.io/en/latest/errors.html"
+            " for details."
+        )
+
     user_attr_keys = set()
     widget_dicts: list[Union[ChoiceWidgetJSON, SliderWidgetJSON, TextInputWidgetJSON]] = []
     for w in widgets: