20. Troubleshooting¶
Use this guide when a run fails and you want the shortest route to a diagnosis.
20.1 First diagnostic commands¶
modssc doctor --json
modssc datasets info --dataset toy
modssc preprocess steps list
modssc graph build --help
python -m bench.main --config bench/configs/experiments/toy_inductive.yaml --log-level detailed
20.2 Common failure patterns¶
20.2.1 modssc works but bench/ commands or configs are missing¶
The benchmark runner lives in the repository and is not shipped to PyPI. Use a source checkout when you need bench.main, authored configs, examples, or notebooks.
20.2.2 Optional dependency error during dataset load, preprocess, or method execution¶
Install the extra suggested by the error message. Dataset specs expose required_extra, preprocess steps expose step metadata, and method registries rely on the extras declared in pyproject.toml.
20.2.3 Unresolved environment variable(s) when loading a YAML config¶
Your config contains placeholders like ${MODSSC_OUTPUT_DIR} or ${MODSSC_CACHE_ROOT} that are not set in the environment. Export them first or remove the placeholders from the YAML.
20.2.4 A transductive run fails because no graph is available¶
Enable the graph: block for non-graph datasets, or switch to a graph dataset/provider that already supplies graph structure.
20.2.5 A graph config is rejected¶
Graph specification validation is strict. If a backend/scheme combination is unsupported, start from a known-good config in the Bench config cookbook and change one field at a time.
20.2.6 The test split does not come from the place you expected¶
respect_official_test: true keeps dataset.test when it exists. allow_override_official: true tells ModSSC to ignore the provider test split for inductive datasets and apply the user split to dataset.train instead.
20.2.7 method.model.factory is rejected¶
This extension hook is disabled by default. You must set run.allow_custom_factories: true explicitly, and you should only do that for configs you control.
20.2.8 A rerun seems to reuse stale artifacts¶
Check which cache root is active (MODSSC_CACHE_ROOT or per-cache overrides). Dataset, preprocess, graph, and views caches are separate layers. If code changed inside one stage, clear only the impacted cache subtree and rerun.
20.3 Trusted-input boundaries¶
- Benchmark configs are trusted local inputs.
- Custom factories are for trusted configs only.
- Dataset and preprocess cache artifacts are trusted local artifacts only.
If you are debugging behavior and you do not trust a cached artifact, clear the relevant cache entry and regenerate it.
20.4 When to escalate from CLI to code inspection¶
- Use the CLI and cookbook configs first when you are debugging environment or schema issues.
- Use the Python API when you need to inspect intermediate objects such as sampling stats, preprocess outputs, or graph artifacts.
- Use the Architecture page when you need to know which package path is public and which one is internal.