{"record":{"id":"94609316d1f19e55","repo":"huggingface/transformers","slug":"unknown-type-for-trial-trial-class","errorCode":null,"errorMessage":"Unknown type for trial {trial.__class__}","messagePattern":"Unknown type for trial (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/transformers/integrations/integration_utils.py","lineNumber":232,"sourceCode":"    return os.getenv(\"KUBEFLOW_TRAINER_SERVER_URL\") is not None\n\n\ndef hp_params(trial):\n    if is_optuna_available():\n        import optuna\n\n        if isinstance(trial, optuna.trial.BaseTrial):\n            return trial.params\n\n    if is_ray_tune_available():\n        if isinstance(trial, dict):\n            return trial\n\n    if is_wandb_available():\n        if isinstance(trial, dict):\n            return trial\n\n    raise RuntimeError(f\"Unknown type for trial {trial.__class__}\")\n\n\ndef run_hp_search_optuna(trainer, n_trials: int, direction: str, **kwargs) -> BestRun:\n    import optuna\n    from accelerate.utils.memory import release_memory\n\n    if trainer.args.process_index == 0:\n\n        def _objective(trial: optuna.Trial, checkpoint_dir=None):\n            checkpoint = None\n            if checkpoint_dir:\n                for subdir in os.listdir(checkpoint_dir):\n                    if subdir.startswith(PREFIX_CHECKPOINT_DIR):\n                        checkpoint = os.path.join(checkpoint_dir, subdir)\n            trainer.objective = None\n            if trainer.args.world_size > 1:\n                if trainer.args.parallel_mode != ParallelMode.DISTRIBUTED:\n                    raise RuntimeError(\"only support DDP optuna HPO for ParallelMode.DISTRIBUTED currently.\")","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/integrations/integration_utils.py#L214-L250","documentation":"hp_params(trial) converts a hyperparameter-search trial object into a params dict. It tries optuna (BaseTrial), then Ray Tune and W&B (both accept plain dicts); if the trial is none of these, it raises RuntimeError('Unknown type for trial ...'). In practice the most common cause is not an exotic trial type but a missing backend: if optuna is not installed, an optuna trial falls through every isinstance check and reaches the raise.","triggerScenarios":"trainer.train(..., trial=<optuna trial>) or Trainer hyperparameter_search with a backend whose package is not importable in the current process (optuna/ray missing or a broken install), so the matching is_..._available() guard skips the only branch that would accept the trial; also genuinely unsupported trial objects (e.g. a SIGOPT or custom sweep trial passed by mistake).","commonSituations":"Running distributed training where the trial is broadcast to worker ranks whose environment lacks optuna; running the Trainer in a subprocess without the training extras; passing a W&B sweep config while neither wandb nor ray is installed.","solutions":["pip install optuna (or ray[tune] / wandb) in the environment that executes the training loop and restart the run.","Verify the trial object you pass matches the installed backend: use optuna Trial objects only when optuna is importable.","For custom HPO frameworks, convert your trial to a plain dict of params before passing it to trainer.train(trial=...).","In multi-node setups, confirm identical package sets on all ranks (pip freeze diff) so worker ranks can recognize the trial."],"exampleFix":"# before\ntrainer.train(trial=optuna_trial)  # optuna not installed -> RuntimeError\n\n# after\nsubprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"optuna\"])\n# restart training, then:\ntrainer.train(trial=optuna_trial)","handlingStrategy":"type-guard","validationCode":"import importlib.util\n\ndef backend_for_trial(trial):\n    if importlib.util.find_spec(\"optuna\") and type(trial).__module__.startswith(\"optuna\"):\n        return \"optuna\"\n    if isinstance(trial, dict) and (importlib.util.find_spec(\"ray\") or importlib.util.find_spec(\"wandb\")):\n        return \"dict-compatible\"\n    raise RuntimeError(f\"install the backend matching trial {type(trial)}\")","typeGuard":"import importlib.util\n\ndef trial_is_supported(trial) -> bool:\n    if importlib.util.find_spec(\"optuna\"):\n        import optuna\n        if isinstance(trial, optuna.trial.BaseTrial):\n            return True\n    if isinstance(trial, dict):\n        return bool(importlib.util.find_spec(\"ray\")) or bool(importlib.util.find_spec(\"wandb\"))\n    return False","tryCatchPattern":"try:\n    params = hp_params(trial)\nexcept RuntimeError as e:\n    if \"Unknown type for trial\" in str(e):\n        params = dict(trial) if hasattr(trial, \"keys\") else trial.params  # convert to plain dict\n    else:\n        raise","preventionTips":["Install the HPO backend in every process/rank that runs trainer.train with a trial.","Pass plain dicts for custom sweep tools instead of foreign trial objects.","Check transformers.utils.is_optuna_available() before entering an optuna sweep."],"tags":["hpo","optuna","dependencies","trainer"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}