Unhelpful error message from treetime when `augur ancestral` fails to load translation alignment

[misacodes]

Description

When augur ancestral fails to load a translation alignment file, the error message is not helpful in diagnosing the actual problem. The error simply states "loading alignment failed" without providing any details about why it failed. I couldn't find anything wrong with the translation at first glance.

Steps to reproduce

1. Run the following command with the attached files:

augur ancestral \
  --tree results/refined_tree.nwk \
  --alignment results/filtered_sequences.fasta \
  --annotation defaults/reference.gb \
  --infer-ambiguous \
  --translations results/translations/%GENE.fasta \
  --genes BCRF1 \
  --output-node-data results/ancestral_node_data.json \
  --output-sequences results/ancestral_sequences.fasta \
  --validation-mode warn \
  --inference joint

2. Observe the error output

Actual output

augur ancestral is using TreeTime version 0.11.4
Read in 2 features from reference sequence file
Processing gene: BCRF1
ERROR: SequenceData: loading alignment failed... results/translations/BCRF1.fasta


ERROR from TreeTime: This error is most likely due to a problem with your input data.
Please check your input data and try again. If you continue to have problems, please open a new issue including
the original command and the error above:  <https://github.com/nextstrain/augur/issues/new/choose>

Expected output

The error message should provide more specific information about why the alignment loading failed, such as:

• Is the file format incorrect?
• Are the sequence IDs mismatched with the tree?
• Are the sequences the wrong length?
• Is there a parsing error at a specific line?
• Any other specific validation failures

Environment

• augur version: 32.0.0 (using TreeTime version 0.11.4)
• Python version: 3.13
• Operating system: macOS

Additional context

The BCRF1.fasta file appears to be properly formatted (contains protein sequences in FASTA format), but the error message doesn't indicate what specifically is wrong. A more descriptive error message would help users quickly identify and fix the issue without having to debug the source code or create an issue.

Attached files

See ancestral_issue.zip containing:

• results/refined_tree.nwk
• results/filtered_sequences.fasta
• defaults/reference.gb
• results/translations/BCRF1.fasta

ancestral_issue.zip

[corneliusroemer]

Root Cause

I reproduced the issue and found the translation file has mismatched sequence lengths. While most sequences are 171 amino acids, three sequences have different lengths:

• AP019183: 722 amino acids
• E01011: 751 amino acids
• FJ428830: 751 amino acids

TreeTime expects all sequences in an alignment to have the same length, but it fails with only "loading alignment failed" without explaining the actual problem.

(The file also contains duplicate sequence IDs like MT648657, though this is secondary to the length mismatch issue.)

Verification

After filtering the file to only include sequences of length 171, the command succeeds.

Suggestion

This validation would be better handled in TreeTime rather than augur:

1. TreeTime is already detecting the problem when loading the alignment
2. TreeTime has context to report which specific sequences have mismatched lengths
3. The fix would benefit all TreeTime users, not just augur

An improved error could be:

ERROR: Failed to load alignment 'BCRF1.fasta'
Sequences have inconsistent lengths:
  - Expected: 171 amino acids (1005 sequences)
  - AP019183: 722 amino acids
  - E01011: 751 amino acids
  - FJ428830: 751 amino acids
All sequences in an alignment must have the same length.