Troubleshooting

Use this page to map common failures to the workflow area that owns the fix. Source code and tests remain authoritative when an error message and a guide appear to disagree.

Malformed or unsupported tree input

If ETE3 cannot parse a Newick string or DendroPy cannot parse a file, first confirm the tree format and schema. Core workflows accept ete3.Tree objects. NEXUS or BEAST-style file reading through DendroPy requires the beast or all extra.

Missing optional dependencies

ModuleNotFoundError for DendroPy means optional tree I/O was used without the beast extra. TrackingError mentioning wandb means tracking was enabled without the wandb extra.

Duplicate or unknown features

TreeFeatureEngineer.add_features() rejects duplicate requested feature names and unknown features. Use engineer.feature_names or engineer.get_available_features() when you need the current supported order.

Invalid graph data

Converters require every requested feature to exist on every node and to be numeric. See Graph Conversion for the canonical graph field contract. Batched model training also needs batch, and temporal modes need data.time_bin.

Invalid TOML training configuration

TrainingConfigError reports malformed TOML, missing sections, unknown keys, wrong types, unsupported loss or metric names, and invalid trainer values. See Training Configuration for the accepted sections.

Tracking setup failures

When tracking is enabled, tracking.project is required. Metadata keys that look secret, such as tokens or passwords, are rejected before external logging. Disable tracking to keep training fully local.

Documentation build failures

Install the docs extra, then run the HTML and doctest builders from the repository root:

python -m pip install -e ".[docs]"
python -m sphinx -b html -n -W --keep-going docs/source docs/_build/html
python -m sphinx -b doctest -W docs/source docs/_build/doctest

Warnings are treated as failures so missing pages, broken references, and stale quickstart snippets are visible before release.