Skip to content

Troubleshooting

Common issues and their solutions.

Installation Issues

"Python version not supported"

Error: Python 3.13+ is required

Solution: Install Python 3.13 or higher.

# Using uv
uv python install 3.13

# Using pyenv
pyenv install 3.13

"Module not found: mi_amore"

ModuleNotFoundError: No module named 'mi_amore'

Solution: The mi-amore library is required. Reinstall Pilz:

uv add pilz --refresh

Training Issues

Training takes too long

Symptoms: Training runs for hours without completing

Solutions:

  1. Reduce n_dims: 

    n_dims: 1  # Instead of 3

  2. Set calcs_per_dim: 

    calcs_per_dim: 1000

  3. Reduce max_eval_fit: 

    max_eval_fit: 500

  4. Reduce n_cat: 

    n_cat: 3  # Instead of 5

Out of memory

Symptoms: Process killed during training

Solutions:

  1. Reduce max_eval_fit
  2. Reduce n_dims
  3. Process data in batches
  4. Use smaller n_cat

"No good split found"

Symptoms: Tree stops early with log messages "Best split yields no branches" or "No feature survived categorization, stop at this node"

Solutions:

  1. Increase max_depth
  2. Decrease min_eval_fit
  3. Try different n_cat values
  4. Check data quality (missing values, outliers)

Data Issues

"Column not found"

KeyError: 'column_name'

Solution: Verify column names in DataCard match CSV headers exactly.

"Target values not found"

ValueError: Target value 'X' not found in column

Solution: Check that target values in DataCard match actual values in CSV.

"Too many missing values"

Option 1: Impute nulls with a fixed value by adding missing_value to the feature in DataCard:

features:
  - name: age
    statistical: numerical
    type: int
    missing_value: 0

Option 2: Leave missing_value unset — nulls then become their own "missing" category that the model can learn from (spores use IS NULL / IS NOT NULL conditions).

Evaluation Issues

"Model not found"

ERROR: folder model/Yes does not exist.

Symptoms: Eval.load_pilze logs folder <path> does not exist. and breaks out of the loop for that target — it does not raise FileNotFoundError.

Solution: - Ensure training completed successfully - Check that in_folders points to correct directory - Check that the target folder is named exactly like the target value

"Label stats not found"

ValueError: label_stats.json not found in [...]. Retrain the model to write label stats

Solution: The multi-class youden combination needs the majority class as the fallback prediction when no threshold margin is positive. Training writes it to label_stats.json alongside the trees. Retrain the model (or resume it — existing trees are skipped) so the file is created, and make sure in_folders points to the model directory.

ROC curve is empty

Symptoms: HTML file has no data points

Solution: - Check that test data has target column - Verify target values match training

Performance Issues

Slow inference

Solutions: 1. Use infer instead of eval (no metrics calculation) 2. Increase max_parallel_where to use fewer, larger SQL batches (legacy cut-models only; lower values create more, smaller batches) 3. Pre-compute predictions and cache

Low accuracy

Solutions: 1. Try higher n_dims (feature combinations) 2. Increase n (more trees) 3. Increase max_depth 4. Adjust n_cat (try 3, 5, 8, 10) 5. Check for data quality issues

Getting Help