19. Common errors and where to go¶
Use this guide when you have an error message or a confusing symptom and want the shortest route to the right documentation page.
19.1 Fast routing table¶
| Symptom or error | Most likely cause | Read this page first |
|---|---|---|
| optional dependency error during dataset load or method execution | missing extra such as graph, hf, preprocess-text, or a torch backend |
Optional extras and platform support |
Unresolved environment variable(s) while loading YAML |
config contains ${VAR} or $VAR placeholders that were not exported |
Configuration reference |
Dataset not found or unclear dataset ID |
wrong dataset key or wrong provider assumptions | Catalogs and registries |
| benchmark config rejected by schema validation | wrong field name, wrong block shape, or unsupported advanced field | Configuration reference |
| transductive run fails because no graph is available | graph block missing, graph build not run, or method kind does not match the data | How to build graphs and views |
method.model.factory rejected |
trusted-only extension hook used without explicit opt-in | Configuration reference |
| split behavior is not the one you expected | confusion between official split policies and custom split policies | How to create and reuse sampling splits |
| rerun seems to reuse stale artifacts | cache reuse is happening across identical fingerprints | Reproducibility |
modssc works but bench/ configs or examples are missing |
package installed from PyPI without repository assets | Installation |
| command exists but available methods or datasets look incomplete | missing extras or registry filtering with --available-only |
Catalogs and registries |
19.2 First commands to run¶
Start with the shortest environment checks:
modssc doctor
modssc --help
modssc datasets list
If the problem comes from a benchmark YAML:
python -m bench.main --config path/to/config.yaml --log-level detailed
19.3 How to decide between this page and troubleshooting¶
- Use this page when you mainly need routing.
- Use Troubleshooting when you already know the subsystem and need a more detailed diagnosis path.
19.4 Terms that often cause confusion¶
If the error message mentions a policy or config field you do not recognize, check the Glossary before diving into the schema or the code.