[tune] cleanup error messaging/diagnose_serialization helper (#10210)

python/ray/tune/experiment.py

@@ -1,5 +1,6 @@
 import copy
 import logging
+from pickle import PicklingError
 import os
 from typing import Sequence
 
@@ -242,7 +243,24 @@ class Experiment:
             else:
                 logger.warning(
                     "No name detected on trainable. Using {}.".format(name))
-            register_trainable(name, run_object)
+            try:
+                register_trainable(name, run_object)
+            except (TypeError, PicklingError) as e:
+                msg = (
+                    f"{str(e)}. The trainable ({str(run_object)}) could not "
+                    "be serialized, which is needed for parallel execution. "
+                    "To diagnose the issue, try the following:\n\n"
+                    "\t- Run `tune.utils.diagnose_serialization(trainable)` "
+                    "to check if non-serializable variables are captured "
+                    "in scope.\n"
+                    "\t- Try reproducing the issue by calling "
+                    "`pickle.dumps(trainable)`.\n"
+                    "\t- If the error is typing-related, try removing "
+                    "the type annotations and try again.\n\n"
+                    "If you have any suggestions on how to improve "
+                    "this error message, please reach out to the "
+                    "Ray developers on github.com/ray-project/ray/issues/")
+                raise type(e)(msg) from None
             return name
         else:
             raise TuneError("Improper 'run' - not string nor trainable.")