get_MNV
Español GitHub

Help

Troubleshooting

This page lists common errors and the quickest fixes.

Contig Names Do Not Match

Example:

[E002] Contig validation failed

Fix:

VCF REF Does Not Match FASTA

Example:

[E002] VCF REF/FASTA mismatch at <contig>:<pos>

Fix:

iVar TSV Is Not Detected

Fix:

Invalid Bases

Example:

[E002] Invalid base 'X' in REF/ALT allele

Fix:

Multiallelic VCF Records

Since 1.1.6 these are split for you, so the error Multiallelic VCF record is not supported no longer appears. An older version needs --split-multiallelic, or a VCF pre-split with bcftools norm -m - input.vcf > split.vcf.

Splitting emits one annotated row per ALT, even when multiple alts share the same codon position. Each row reports its own amino-acid effect, codon, and BAM-derived read support. Pre-splitting the VCF with bcftools norm -m - produces the same output.

BCF Input

Since 1.1.6 a .bcf is read directly through --vcf. Older versions stop with BCF input is not supported. Convert to VCF first; convert with bcftools view input.bcf > input.vcf for those.

A BCF that is cut short, for example by an interrupted copy, stops the run with an invalid BCF record or invalid BCF header error rather than reading as a VCF with fewer records. Copy the file again.

TSV Annotation with Multiple Contigs

Example:

TSV annotation has 2 row(s) without a contig, which cannot be placed in a multi-contig VCF

Fix:

Versions before 1.1.6 had no contig column and gave TSV annotation does not include contig names instead.

Fewer Rows Than Records in the VCF

Example:

Skipped 148 ALT alleles the selected sample's genotype does not carry

Cause: a VCF record lists every ALT seen at that site across every sample, so the selected sample's GT decides which of them belong to it. A genotype of 0/0 carries none, and on a multiallelic record 1/1 carries only the first ALT.

Fix:

Sample Name Not Found

Example:

Sample '<name>' not found in VCF header

Fix:

Strict Mode Fails

Example:

--strict enabled, but original VCF metrics are missing

Fix:

Filtering by Allele Frequency

Use --min-snp-frequency <F> for SNP records and --min-mnv-frequency <F> for MNV haplotypes. Values are fractions from 0 to 1, so 0.05 means 5%.

These filters require --bam because get_MNV calculates them from read support. They do not use the original VCF/iVar OFREQ value. The SNP and MNV thresholds are independent. In mixed SNP/MNV calls, --min-snp-frequency filters SNP observations and --min-mnv-frequency filters the phased MNV haplotype; a strong MNV should not disappear only because individual SNP observations are below the SNP threshold.

Common fixes:

Output Directory Is Not Writable

Example:

Read-only file system

Fix:

Warnings

A warning never stops the run, so it is easy to scroll past. These are the ones that change what ends up in the output, and none of them is visible in the TSV itself: if the annotation of a variant is not what you expected, or its metrics came from a sample you did not pick, the reason was on stderr.

None of them removes a variant. A base get_MNV cannot place in a codon is still reported, as a row naming its gene with - in every amino acid column, so the symptom to look for is an unannotated row rather than a missing one.

The amino acid call is missing for a variant that is inside a gene

WarningWhat it meansWhat to do
falls in the phase-skipped region of CDS ...The codon spans into a neighbouring exon, and a single GFF row cannot say what the neighbouring bases are, so no codon is built for that base. The variant is still reported: one row naming the gene, - in every amino acid column, and SO term coding_sequence_variant (MODIFIER).Give the CDS rows a transcript_id or Parent so get_MNV can splice the transcript, and run with --gff-features CDS.

The annotation is coarser than the file could support

The first three fall back to per-feature annotation, so codons are grouped inside one CDS row instead of across the spliced transcript, and a variant near an exon boundary can then get a different amino acid call. The fourth changes nothing on its own.

WarningWhat it meansWhat to do
has rows on both strandsTwo rows of one transcript disagree about orientation, and a spliced CDS cannot be built from them.Fix the strand column, or split the rows into separate transcripts.
has a single CDS row with non-zero phase / starts with non-zero phaseThe selected rows do not look like a whole coding sequence, so the phase cannot be trusted to place the codons.Include every CDS row of the transcript in the run.
contains CDS rows with non-zero phase, but --gff-features does not include 'CDS'Codon grouping is ignoring phase the file provides.Add --gff-features CDS.
lists N duplicate CDS row(s)get_MNV drops the repeats itself and still builds the spliced transcript, so the annotation is the same one a clean file would give.Nothing. Deduplicating the GFF only silences the warning.

The metrics come from a sample you did not choose

WarningWhat it meansWhat to do
Multi-sample VCF detected (N samples). Using first sampleODP and OFREQ are read from whichever sample comes first in the header, which is rarely a deliberate choice. That sample's genotype also decides which ALT alleles are kept, so the choice changes the row count too (see Fewer Rows Than Records in the VCF).Name one with --sample, or annotate every one with --sample all.

The read support is not what the input claimed

WarningWhat it meansWhat to do
has N spanning read(s) but 0 with exact CIGAR supportReads cover the site but none of them carries that exact indel, which is what happens when the allele is written at a different position inside a homopolymer or repeat.Rerun with --left-align, or left-align the input first with bcftools norm -f ref.fa. If the warning says the allele is already left-aligned, the reads place the gap elsewhere or do not carry the indel: look at the alignment.
was declared X by the input VCF, but N of M reads spanning the site carry the whole haplotypeThe caller and the reads disagree about whether these changes travel together.Look at the alignment before trusting either.
shows N distinct combinations on the reads; reporting the K best supportedA window with more local haplotypes than get_MNV reports. The dropped ones are the weakly supported tail. See Indels and Local Haplotypes.Nothing, unless a rare haplotype matters; --chrom takes whole contig names, not regions, so inspect the window in the alignment instead.

A flag did nothing

WarningWhat it means
--keep-original-info has no effect with iVar TSV inputAn iVar TSV has no INFO column to preserve.
--gff-features is ignored when using TSV annotation format (--genes)Feature types are a GFF/GTF idea; the four-column TSV has none.

A threshold reached less than you meant

WarningWhat it means
The MNV thresholds will not remove any SNP/MNV rowThe MNV thresholds are still filtering MNV, indel and intergenic rows. What they cannot reach is the SNP/MNV rows: one survives when either its SNVs or its haplotype clears its bar, so with the SNP thresholds at 0 the SNP side always passes. Raise --snp, --min-snp-frequency or --min-snp-strand as well to filter codon-level rows.

An optional external program was missing

WarningWhat it means
bcftools not found in PATH. Skipping BCF output.--bcf was asked for and no BCF was written. The run continues and exits 0; the TSV and VCF are unaffected, and the summary JSON reports no BCF. Install bcftools, or drop --bcf.
tabix not found in PATH. Skipping .tbi index--index-vcf-gz was asked for and no .tbi was written. The .vcf.gz itself is complete. Install samtools/htslib, or index it later with tabix -p vcf <file>.

Flag Conflicts

ErrorFix
--index-vcf-gz requires --vcf-gzAdd --vcf-gz.
--bcf requires --convert or --bothAdd --convert or --both.
--keep-original-info requires --convert or --bothAdd --convert or --both.
--min-strand-bias-p must be between 0 and 1Use a value from 0 to 1.

Exit Codes

CodeMeaning
0Success
1Generic error
2Configuration error
3Input validation error
10File read/write error
11CSV/TSV parsing error
12BAM/VCF parsing error
13UTF-8 encoding error
14Integer parsing error
15Floating-point parsing error
16JSON error

Still stuck?

Everything above is a message the tool can produce and what it is asking for. If what you are seeing is not here, or the answer here did not fit your data, ask in Q&A.

Answers there get marked as answers, so the next person with your problem finds it before they have to ask.

Edit this page on GitHub