Troubleshooting¶

Solutions to common problems when using Sklearn-Optuna.

Installation Issues¶

Problem: Package not found

Verify the package name: pip install sklearn-optuna or uv add sklearn-optuna.

Problem: Import error after installation

Make sure you installed in the active environment: python -c "import sklearn_optuna".

Problem: Optuna version conflict

Sklearn-Optuna requires Optuna 3.5-3.x. If you have Optuna 4.x installed, downgrade with pip install "optuna>=3.5,<4".

Search Issues¶

Problem: Results are not reproducible

Wrap the sampler with Sampler and pass seed=. Use n_jobs=1 because parallel trial ordering is non-deterministic. See How to Configure Samplers.

Problem: All trials return NaN

The estimator may be failing silently. Set error_score="raise" to surface the underlying error. See How to Handle Errors.

Problem: Search is slow

Reduce n_trials or set a timeout to cap execution time. Check that cv is not set to a large number of folds. Consider using n_jobs=-1 for parallel trial execution on a single machine, or distribute trials across multiple nodes with a shared database storage (see Concepts: Multi-node optimization).

Problem: CMA-ES sampler raises an error

CMA-ES does not support CategoricalDistribution parameters. Use TPESampler for mixed search spaces.

Pipeline Issues¶

Problem: Parameter not found in pipeline

Use double-underscore syntax to address nested parameters: "clf__C" for the C parameter of the clf step. See How to Use in Pipelines.

Problem: OptunaSearchCV does not work as a pipeline step

OptunaSearchCV is a valid Scikit-Learn estimator and works as a pipeline step. Make sure you pass it as a step tuple: ("search", search).

Storage Issues¶

Problem: Study not resuming from database

Make sure you use the same study_name and Storage configuration. See How to Persist and Resume Studies.

Getting Help¶

• Open an issue on GitHub
• Start a discussion

Docs build fails with a snippet-not-found error after a template update¶

Problem: After updating from the template, just build fails with an error naming a file that a --8<-- include cannot find.

Cause: The docs build now sets check_paths: true for pymdownx.snippets. Previously a missing include was dropped silently, so the page rendered without the included content and looked deliberate. The error is surfacing an include that was already broken, not a new one.

Fix: Either point the include at a file that exists, or remove the include (and the page, if the include was all it contained). Include paths resolve relative to docs/ first, then the repository root, so --8<-- "CHANGELOG.md" finds the changelog at the top of the repo.