From a005908440faaa9fead666c62a7787c1cdf11357 Mon Sep 17 00:00:00 2001
From: c-bata <contact@c-bata.link>
Date: Mon, 10 Apr 2023 14:44:45 +0900
Subject: [PATCH] Show warning about the use of _CachedStorage

Co-authored-by: Kenshin Abe <abe.kenshin@gmail.com>
---
 docs/errors.rst                  | 24 ++++++++++++++++++++++++
 docs/index.rst                   |  1 +
 optuna_dashboard/_form_widget.py | 20 ++++++++++++++++++++
 3 files changed, 45 insertions(+)
 create mode 100644 docs/errors.rst

diff --git a/docs/errors.rst b/docs/errors.rst
new file mode 100644
index 00000000..ef936ef3
--- /dev/null
+++ b/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
diff --git a/docs/index.rst b/docs/index.rst
index 996621bc..c12e83c4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Real-time dashboard for `Optuna <https://github.com/optuna/optuna>`_.
 
    installation
    api
+   errors
 
 
 Links
diff --git a/optuna_dashboard/_form_widget.py b/optuna_dashboard/_form_widget.py
index e78ee4fc..8afda925 100644
--- a/optuna_dashboard/_form_widget.py
+++ b/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: