Skip to content

Troubleshooting FAQ

Common issues and their solutions.

Installation & Environment

nbdev-test crashes with ImportError: cannot import name 'strip_ansi'

Cause: The execnb package installed via conda is outdated (v0.1.11) and incompatible with modern IPython.

Fix: Upgrade via pip: 

pip install --upgrade execnb nbdev

This installs execnb >= 0.1.18 which resolves the strip_ansi deprecation.

ModuleNotFoundError: No module named 'kreview.features.xyz'

Cause: The notebooks have been edited but nbdev-export was not run.

Fix: 

nbdev-export

This regenerates all kreview/*.py files from the notebooks.

AttributeError: module 'kreview.eval_engine' has no attribute 'xyz'

Cause: The function exists in the notebook but the cell is missing the #| export directive.

Fix: Open the notebook in nbs/, find the cell with the function, and add #| export at the top of the cell. Then run nbdev-export.

Pipeline Execution

PermissionError: [Errno 1] Operation not permitted during large cohort loading

Cause: DuckDB is trying to open more parquet file handles than the OS allows.

Fix: Reduce the chunk size: 

kreview run ... --chunk-size 100

The pipeline also has built-in exponential backoff retry (3 attempts with 1s/2s/4s delays), so transient failures are handled automatically.

Empty feature matrix — evaluator produces no output

Cause: The parquet suffix in the evaluator's source_file doesn't match the actual files on disk.

Fix: Check the evaluator class definition: 

class MyEvaluator(FeatureEvaluator):
    source_file = ".MyFeature.ontarget.parquet"  # Must match exactly!

Verify the file exists for at least one sample: 

ls /path/to/krewlyzer/SAMPLE_ID/SAMPLE_ID.MyFeature.ontarget.parquet

Feature evaluator not found in registry

Cause: The evaluator class was not exported from the notebook, or it doesn't subclass FeatureEvaluator.

Fix: 1. Ensure the notebook cell has #| export 2. Ensure the class inherits from FeatureEvaluator 3. Run nbdev-export 4. Verify with kreview features-list

AttributeError: 'FinetunedTabPFNClassifier' has no attribute 'classes_'

Cause: TabPFN's classes_ is a @property that raises AttributeError on unfitted models. sklearn's cross_val_predict probes classes_ before fitting, triggering this error.

Fix: Upgrade to kreview ≥ v0.0.18. The GPUModelCVAdapter wrapper exposes classes_ as a plain attribute set during fit(), making GPU models fully compatible with sklearn's CV infrastructure.

If you see this error on v0.0.18+, ensure your eval_engine.py is regenerated from the notebook: 

nbdev-export

Decomposed multimodal pipeline — single model step fails

Cause: When running the decomposed pipeline (kreview eval multimodal prep → single → ablation → merge), one model's single step may fail (e.g., GPU OOM, TabPFN token expired) while others succeed.

Fix: The merge step gracefully handles missing model JSONs — it aggregates whatever results are available and logs warnings for missing models. Re-run only the failed single step: 

kreview eval multimodal single \
    --stacking-matrix results/multimodal/stacking_matrix.parquet \
    --model tabpfn_ft --device cuda --output results/multimodal/
Then re-run ablation and merge to incorporate the recovered results.

Ablation produces NO_BEST_SUBSET sentinel — ablation was skipped

Cause: params.run_ablation = false (the default) in Nextflow. The pipeline emits sentinel files (NO_BEST_SUBSET) that EVAL processes detect and ignore.

Fix: This is expected behavior when ablation is disabled. To enable: 

nextflow run ... --run_ablation true --ablation_inner_folds 3

GPU ablation failed but CPU continued — is that expected?

Cause: GPU ablation processes use set +e to prevent pipeline-level failures. If GPU ablation fails (OOM, timeout, missing GPU), an error JSON is emitted instead of results. The merge step detects this and falls back to CPU-only ablation results.

Fix: This is by design — the pipeline prioritizes completion over GPU availability. Check the Nextflow log for the specific GPU failure. If GPU ablation is critical, increase memory/time limits in nextflow.config: 

withName: 'KREVIEW_ABLATE_GPU_SINGLE' {
    memory = { 128.GB * task.attempt }
    time   = { task.attempt <= 1 ? 4.h : 8.h }
}

Holdout AUC error after ablation — dimension mismatch

Cause: This was a known bug (fixed in v0.0.20) where the holdout evaluation received the full feature matrix but the refitted model expected a feature subset from ablation.

Fix: Upgrade to kreview ≥ v0.0.20, which stores {model}_refit_features in the results and uses it to slice X_test correctly before holdout evaluation.

Dashboard & Reports

Quarto not found — dashboard generation skipped

Cause: Quarto CLI is not installed in your environment.

Fix: Install Quarto from quarto.org or use the Docker image which includes Quarto pre-installed.

Alternatively, skip reports entirely: 

kreview run ... --skip-report

SHAP plots show blank — only RF appears, no XGBoost

Cause: XGBoost failed to import silently. The engine degraded to RF-only mode.

Fix: Install XGBoost explicitly: 

pip install xgboost>=2.0.0

Git & nbdev

Massive diffs in notebook files on git diff

Cause: Jupyter notebook metadata (execution counts, outputs) was not stripped.

Fix: 

nbdev-clean
nbdev-install-hooks  # Prevents this in the future

I accidentally edited a .py file directly. How do I fix it?

Run nbdev-update to sync your changes back to the notebooks: 

nbdev-update

Then verify and re-export: 

nbdev-export