Summary: When a GTF file is malformed/truncated such that no genes can be extracted from it, RustQC correctly logs a warning about the parse failure, but the subsequent fatal error misdiagnoses the root cause as a chromosome naming mismatch between the BAM and GTF, and prints an empty/useless chromosome_mapping suggestion. This is misleading for anyone debugging a bad annotation file — the real problem (malformed GTF) is buried in an easy-to-miss WARN line above it.
Environment:
- RustQC 0.2.1 (
c868466, built 2026-04-09), Docker image seqinfomics/rustqc:0.2.1, run via Apptainer 1.4.5
Steps to reproduce:
Truncate a valid GTF so it's missing required columns (e.g. keep only the first 5 of 9 tab-separated fields), then run:
rustqc rna sample.bam --gtf truncated.gtf --paired --stranded reverse --skip-dup-check --outdir out/
Actual output:
Parsing GTF annotation...
[WARN rustqc::gtf] No genes extracted from GTF file './truncated.gtf'. Check that the file is in GTF (not GFF3) format and contains exon features with gene_id attributes.
Processing sample.bam
✗ error: Failed to process sample.bam: Chromosome name mismatch: no reads could be assigned to any gene.
Alignment chromosomes (first 5): chr1, chr10, chr11, chr12, chr13
GTF chromosomes (first 5):
The alignment and GTF files appear to use different chromosome naming conventions.
To fix this, create a YAML config file with a chromosome_mapping section and pass it via --config:
Example config.yaml:
chromosome_mapping:
Error: 1 file(s) failed to process
Note the GTF chromosomes (first 5): line is empty, and the suggested chromosome_mapping: block has nothing after it — because there are zero chromosomes in the parsed GTF, not because of a naming convention mismatch.
Expected: When the GTF parse step already determined that 0 genes were extracted, the "no reads assigned" error path should surface that as the root cause (e.g. "GTF annotation is empty or malformed — see the warning above") rather than falling through to the chromosome-mismatch diagnosis, which doesn't apply here and offers a suggested fix (chromosome_mapping) that cannot possibly help.
Fix suggestion: Track whether 0 genes were extracted from the GTF during parsing, and short-circuit the "no reads assigned to any gene" error with a distinct, GTF-parse-specific message when that's the case, instead of always defaulting to the chromosome-naming-mismatch diagnosis.
Summary: When a GTF file is malformed/truncated such that no genes can be extracted from it, RustQC correctly logs a warning about the parse failure, but the subsequent fatal error misdiagnoses the root cause as a chromosome naming mismatch between the BAM and GTF, and prints an empty/useless
chromosome_mappingsuggestion. This is misleading for anyone debugging a bad annotation file — the real problem (malformed GTF) is buried in an easy-to-missWARNline above it.Environment:
c868466, built 2026-04-09), Docker imageseqinfomics/rustqc:0.2.1, run via Apptainer 1.4.5Steps to reproduce:
Truncate a valid GTF so it's missing required columns (e.g. keep only the first 5 of 9 tab-separated fields), then run:
Actual output:
Note the
GTF chromosomes (first 5):line is empty, and the suggestedchromosome_mapping:block has nothing after it — because there are zero chromosomes in the parsed GTF, not because of a naming convention mismatch.Expected: When the GTF parse step already determined that 0 genes were extracted, the "no reads assigned" error path should surface that as the root cause (e.g. "GTF annotation is empty or malformed — see the warning above") rather than falling through to the chromosome-mismatch diagnosis, which doesn't apply here and offers a suggested fix (
chromosome_mapping) that cannot possibly help.Fix suggestion: Track whether 0 genes were extracted from the GTF during parsing, and short-circuit the "no reads assigned to any gene" error with a distinct, GTF-parse-specific message when that's the case, instead of always defaulting to the chromosome-naming-mismatch diagnosis.