# VCF Header Mismatch Fix: Common Problems and Fixes The most likely cause of a VCF header mismatch is a contig naming disagreement, usually `chr1` in one file and `1` in another, or `chrM` versus `MT`. The first thing to check is the `##contig` lines in the header against the contigs that actually appear in the body, then against the reference sequence dictionary used by your pipeline. A Variant Call Format file is not a simple text table. Its header declares the file format, reference assembly, contig names and lengths, INFO fields, FORMAT fields, FILTER values, ALT allele types, and sample columns. When the header disagrees with the body, or when two VCFs disagree with each other, tools may stop with an error, silently skip records, or produce annotations that look plausible but are wrong. The repair is rarely a single text edit. A safe VCF header mismatch fix starts with identifying which layer is inconsistent: header versus body, header versus header, or header versus reference. Each layer has a different failure mode and a different correct fix. Annotation tools make the cost of a mismatch visible. Tools such as vcfanno match records by chromosome, position, reference allele, and alternate allele, so a header that misstates contig naming or allele conventions can turn a real variant into a no-match [1]. The same principle applies to joint calling, filtering, and clinical interpretation. ## What a VCF Header Mismatch Actually Means A VCF file has two parts. The header begins with lines that start with `##`, followed by the column line that starts with `#CHROM`. The body contains tab-delimited records, one variant per line, with columns for chromosome, position, identifier, reference allele, alternate allele, quality, filter, INFO, FORMAT, and one genotype column per sample. The header is a machine-readable schema. It tells parsers what types to expect. An INFO field declared as `Type=Integer` cannot hold a decimal value. A FORMAT field declared as `Number=1` cannot hold three values. A sample column named in `#CHROM` must have a matching genotype field in every body line. A contig used in the body should be declared with a `##contig` line when the consuming tool requires a complete sequence dictionary. A header mismatch is any disagreement between that schema and the data or between two schemas that must be combined. The disagreement can be structural, such as a missing `##contig` line for `chr7`. It can be semantic, such as `##contig=` in a file built on GRCh38. It can be textual, such as duplicate `##INFO` lines with different `Type` values. It can also be a sample-level mismatch, such as two VCFs that both list `SAMPLE1` but represent different individuals. ### Header versus body A header-body mismatch appears when the body uses a contig, INFO tag, FORMAT tag, or FILTER value that the header does not define, or when the number of sample columns in the body does not match the sample list in `#CHROM`. Strict parsers reject the file. Lenient parsers may add missing definitions on the fly, which hides the problem until a different tool reads the file. ### Header versus header A header-header mismatch appears when merging, concatenating, or comparing VCFs. One file may use `chr1` and another `1`. One file may declare `##contig=` and another may declare a different length. One file may define `##INFO=` and another may define `DP` as `Type=Float`. These conflicts must be resolved before merge or joint annotation. ### Header versus reference A header-reference mismatch appears when the VCF claims one reference assembly but the coordinates or REF alleles match another. This is more serious than a naming difference. Changing `chr1` to `1` is a header fix. Changing GRCh37 coordinates to GRCh38 coordinates is a liftover or re-calling problem. A header edit alone cannot repair a genuine assembly mismatch. ### How VCF Headers Differ from FASTA and FASTQ Across bioinformatics file formats, VCF is unusual because its header is a typed schema. A FASTA file has a header line beginning with `>` that carries an identifier and optional description, followed by sequence lines. A FASTQ file has four lines per read: an `@` header, the sequence, a `+` separator, and a quality string. FASTQ stores per-base quality scores, while FASTA stores sequence only. The [FASTQ vs FASTA](/knowledge/bioinformatics/fastq-vs-fasta) distinction matters when a pipeline error is vague. A FASTQ or FASTA file fed to a VCF tool does not produce a true VCF header mismatch. It produces a parse error, often because the first line is not `##fileformat=VCF` or because the file lacks a `#CHROM` column line. Confirm the file type before editing a header. A valid VCF header is not interchangeable with a FASTA description line or a FASTQ read identifier. ## Quick Diagnosis: The First Checks Run these checks on a copy of the file. Keep the original untouched until the repaired file passes validation. 1. Confirm the file type and compression. ```bash file input.vcf.gz bcftools view -h input.vcf.gz | head ``` A VCF header should begin with `##fileformat=VCFv4.x`. If `bcftools view` fails, try `bcftools view -h input.vcf` on the uncompressed file. A BCF file is binary and must be read with `bcftools`, not with `zcat`. 2. List the contigs declared in the header. ```bash bcftools view -h input.vcf.gz | grep '^##contig' ``` 3. List the contigs that actually appear in the body. ```bash bcftools view -H input.vcf.gz | cut -f1 | sort -u ``` 4. Compare the two lists. A contig in the body with no header line is a common mismatch. A contig in the header with a length that disagrees with the reference `.dict` or `.fai` is a sequence dictionary mismatch. 5. List the sample columns. ```bash bcftools query -l input.vcf.gz ``` 6. Inspect the `#CHROM` line directly. ```bash bcftools view -h input.vcf.gz | grep '^#CHROM' ``` The sample names in this line must match the sample names used by the pipeline and must be unique. The number of sample columns must match the number of genotype fields in every body line. 7. Run a validator if one is available. ```bash vcf-validator input.vcf.gz ``` Validation catches undefined INFO tags, malformed header lines, duplicate definitions, and body lines with the wrong number of columns. A validator is not a substitute for checking the reference assembly, but it is a fast first pass. ## Troubleshooting Table | Symptom | Likely cause | How to confirm | Fix | |--|--|--|--| | `Contig 'chr1' is not defined in the header` | Body uses a contig missing from `##contig` lines | Compare header contigs with body contigs | Add correct `##contig` lines from the reference dictionary, then reindex | | Tool reports `sequence dictionary` mismatch | Contig lengths or order differ from the reference `.dict` | Compare `##contig` lengths with the `.dict` or `.fai` | Replace contig lines with the reference dictionary, then validate | | `chr1` records never match `1` annotations | Header uses one naming style and annotation source uses another | Check `##contig` and annotation chrom column | Harmonize naming before annotation, not after | | `Duplicate sample name` during merge | Two VCFs use the same sample ID for different samples | List sample columns in both files | Rename samples with `bcftools reheader -s`, then merge | | `Sample ... not found in header` after subsetting | `#CHROM` line was edited without updating genotype columns | Compare sample list with body column count | Rebuild the file with `bcftools view -s`, do not hand-edit | | `INFO tag DP is not defined` | Body uses `DP` but header lacks `##INFO=` | Search header for `##INFO="}' reference.fa.fai > contigs.hdr ``` Then rebuild the header so the new contig lines appear before `#CHROM`. ```bash bcftools view -h input.vcf.gz | grep -v '^##contig' > base.hdr grep -v '^#CHROM' base.hdr > base.nochrom.hdr grep '^#CHROM' base.hdr > chrom.hdr cat base.nochrom.hdr contigs.hdr chrom.hdr > new.hdr bcftools reheader -h new.hdr -o repaired.vcf.gz input.vcf.gz ``` This is a header repair. It does not change coordinates. If the VCF was called against a different assembly, stop here and liftover or re-call. A dictionary that matches the new reference does not make old coordinates correct. ### 3. Sample Columns and Duplicate Sample Names Sample mismatches are common after merging, subsetting, or renaming. The `#CHROM` line lists sample IDs. Every body line must have one FORMAT field and one genotype field per sample. If you remove a sample name from the header without removing its genotype column, the file becomes malformed. Duplicate sample names cause a different failure. Two VCFs may both contain `SAMPLE1` but represent different individuals. A merge tool cannot distinguish them. It may refuse to merge or may produce a file with ambiguous genotypes. Confirm the sample list. ```bash bcftools query -l input.vcf.gz bcftools view -h input.vcf.gz | grep '^#CHROM' ``` Rename samples with a two-column mapping file, old name followed by new name. ```bash bcftools reheader -s rename.txt -o renamed.vcf.gz input.vcf.gz ``` Subset samples with `bcftools view`, not with a text editor. ```bash bcftools view -s sample1,sample2 -Oz -o subset.vcf.gz input.vcf.gz ``` After any sample change, validate the number of columns in the body. A header edit that leaves the body unchanged creates a file that looks correct in the header and fails on the first data line. ### 4. Missing INFO, FORMAT, FILTER, and ALT Definitions VCF body lines can carry tags such as `DP`, `AF`, `AD`, `GT`, `GQ`, `LowQual`, or `DEL`. Each tag needs a header definition. The definition states the tag ID, number of values, type, and description. A missing definition is a header mismatch even when the values themselves are valid. Strict parsers fail on missing definitions. Lenient parsers may invent a definition, which can change how downstream tools interpret the field. An INFO field that should be `Type=Integer` may be treated as a string. A FORMAT field that should have `Number=R` may be treated as `Number=1`. The result is a silent type error. Annotation adds another layer. vcfanno and similar tools add INFO fields from annotation sources, and those fields must be declared correctly in the output header [1]. If the annotation source supplies a value for a tag that is undefined or defined with the wrong type, the output can fail validation. Inspect the header definitions. ```bash bcftools view -h input.vcf.gz | grep '^##INFO' bcftools view -h input.vcf.gz | grep '^##FORMAT' bcftools view -h input.vcf.gz | grep '^##FILTER' ``` Add missing lines with a header fragment. ```bash cat extra_definitions.hdr bcftools annotate -h extra_definitions.hdr -Oz -o fixed.vcf.gz input.vcf.gz ``` Use the correct `Number` and `Type`. A genotype likelihood field with three values per sample is not `Number=1`. An allele depth field with one value per allele is not `Number=1` unless the VCF is biallelic and the definition says so. If you do not know the type, fix the source caller or annotation tool rather than guessing. A wrong definition is worse than a missing one because it passes validation and corrupts downstream analysis. ### 5. Conflicting Duplicate Header Lines Duplicate header lines are a subtler mismatch. A file may contain two `##INFO` lines for `DP`, one with `Type=Integer` and one with `Type=Float`. A merger may concatenate headers from two sources and keep both. Some parsers use the first definition. Some use the last. Some reject the file. The behavior depends on the tool. Duplicate `##contig` lines with different lengths are especially risky. The body coordinates are interpreted against one length while the index or reference dictionary uses another. This can produce off-by-one or out-of-range errors that look like alignment problems. Find duplicate IDs. ```bash bcftools view -h input.vcf.gz | grep '^##INFO' | sort bcftools view -h input.vcf.gz | grep '^##FORMAT' | sort bcftools view -h input.vcf.gz | grep '^##contig' | sort ``` Do not run `sort -u` on the entire header and assume the result is valid. Header line order matters. `##fileformat` must come first, and `#CHROM` must come last. Resolve duplicates by choosing the definition that matches the body values, then remove the conflicting line. Validate after the edit. ### 6. Merge and Joint Calling Artifacts Merging VCFs combines headers. If the input files used different contig naming, different INFO definitions, different FILTER vocabularies, or different sample naming, the merged header inherits the conflict. A merge can succeed while producing a file with duplicate definitions or a sample list that no longer matches the genotype columns. Joint calling adds another risk. Joint-called VCFs often include FORMAT fields such as `PL`, `AD`, and `GQ` that were not present in the single-sample inputs. The header must be updated to match the new FORMAT fields. If the caller writes the fields but the header update fails, the VCF is malformed. Preflight the inputs before merge. ```bash bcftools query -l a.vcf.gz bcftools query -l b.vcf.gz bcftools view -h a.vcf.gz | grep '^##contig' bcftools view -h b.vcf.gz | grep '^##contig' ``` Merge only after the contig names, contig lengths, sample names, and tag definitions agree. For allele-specific annotation, the VCF and annotation source must use the same REF and ALT representation [1]. A merge that changes allele representation without normalizing the annotation source creates a silent mismatch. ### 7. Compression, Index, and BCF Staleness A stale index is not a header mismatch, but it is one of the most common problems after a header repair. You run `bcftools reheader`, the header looks correct, and the tool still fails because the `.tbi` or `.csi` index was built from the old file. VCF files used by region queries must be bgzip-compressed, not ordinary gzip-compressed. The two formats look similar with `file`, but tabix and bcftools index require bgzip blocks. A plain gzip VCF can be read sequentially and fail on random access. Confirm compression and indexing. ```bash file input.vcf.gz bcftools index -n input.vcf.gz ``` Recompress and reindex after any header or body change. ```bash bgzip -c repaired.vcf > repaired.vcf.gz tabix -p vcf repaired.vcf.gz ``` For BCF, use `bcftools index`. ```bash bcftools index repaired.bcf ``` Safety note: do not overwrite the only copy of a VCF with a redirection such as `bcftools view in.vcf.gz > in.vcf.gz`. The shell truncates the input before the command reads it. Write to a new filename, validate the new file, then replace the original. ### 8. Fileformat Version and Malformed Header Lines The first header line must be `##fileformat=VCFv4.x`. If it is missing, misspelled, or preceded by another line, parsers may reject the file. Version differences between VCFv4.1, VCFv4.2, and VCFv4.3 are usually handled by modern tools, but older tools may reject a newer version. Malformed header lines are a separate problem. A missing closing angle bracket, an unquoted description with a comma, or a `Type` value that is not one of `Integer`, `Float`, `Flag`, `Character`, or `String` can break parsing. These errors are easy to introduce with manual edits. Inspect the first lines and the structure of complex definitions. ```bash bcftools view -h input.vcf.gz | head bcftools view -h input.vcf.gz | grep '^##INFO' | head ``` Do not change `##fileformat` to a different version unless you know the body is compatible. Convert the file with a supported tool instead. A version string edit does not change the data model. ### 9. Reference Allele and Symbolic Allele Conflicts A header can declare the correct reference file while the body contains REF alleles that do not match that reference. This is a data mismatch, but it often surfaces as a header or reference error because tools compare the header reference line, the sequence dictionary, and the REF column together. Symbolic alleles add complexity. A [structural variant](/blog/guides/structural-variant) may use ``, ``, ``, or breakend notation. The header needs `##ALT` definitions for symbolic alleles and correct INFO definitions for `END`, `SVLEN`, and related fields. A tool that does not understand the symbolic allele may treat it as a simple substitution. An annotation source with REF and ALT columns may fail to match if the symbolic representation differs [1]. Check REF alleles against the reference. ```bash bcftools norm -f reference.fa -c w -Oz -o normalized.vcf.gz input.vcf.gz ``` If the command reports many REF mismatches, stop. The problem is not the header. The VCF may have been called against a different reference, or the reference FASTA may be the wrong assembly. Fix the reference before editing contig lines. ## How to Fix a VCF Header Mismatch Safely A safe repair follows a fixed sequence. Do not skip validation. Do not edit the original file in place. 1. Copy the input and record checksums. ```bash cp input.vcf.gz work.vcf.gz sha256sum input.vcf.gz work.vcf.gz ``` 2. Inspect the header and body contigs. ```bash bcftools view -h work.vcf.gz | grep '^##contig' bcftools view -H work.vcf.gz | cut -f1 | sort -u ``` 3. Inspect sample columns and body width. ```bash bcftools query -l work.vcf.gz bcftools view -h work.vcf.gz | grep '^#CHROM' ``` 4. Run a validator and save the log. ```bash vcf-validator work.vcf.gz > validation.log 2>&1 ``` 5. Build a corrected header fragment. Add only lines that are supported by the reference and the body. For contigs, use the reference `.fai` or `.dict`. For INFO and FORMAT, use the definitions from the caller or annotation tool that produced the data. 6. Reheader into a new file. ```bash bcftools reheader -h new.hdr -o step1.vcf.gz work.vcf.gz ``` 7. Normalize alleles if the reference is available. ```bash bcftools norm -f reference.fa -c w -Oz -o step2.vcf.gz step1.vcf.gz ``` 8. Validate the repaired file, then index it. ```bash vcf-validator step2.vcf.gz bcftools index -t step2.vcf.gz ``` 9. Compare sample counts and record counts before and after. ```bash bcftools query -l step2.vcf.gz | wc -l bcftools view -H step2.vcf.gz | wc -l ``` A reheader changes the header. It does not change the body. If the body has undefined tags, a reheader alone will not fix the file. If the body has the wrong number of sample columns, a reheader alone will make the mismatch worse. Use `bcftools view` or `bcftools annotate` for body-aware changes. Safety note: keep the original file and the validation log until the repaired file passes all downstream steps. A VCF that passes `bcftools view` can still fail in GATK, a joint caller, or a clinical reporting pipeline. ## Prevention Practices Prevention is cheaper than repair. These practices reduce VCF header mismatch incidents. 1. Standardize contig naming at the pipeline boundary. Choose `chr`-prefixed or Ensembl-style names once and apply the rule to references, annotation sources, and all VCFs. 2. Pin the reference assembly and sequence dictionary. Record the FASTA, `.fai`, and `.dict` versions in the pipeline manifest. Do not mix patches silently. 3. Validate every VCF after generation, merge, annotation, and filtering. A validator catches undefined tags and malformed lines before they reach a downstream tool. 4. Keep annotation sources on the same contig naming and allele representation as the VCF. For vcfanno, verify that annotation records carry matching chromosome, position, REF, and ALT fields when allele-specific matching is used [1]. 5. Avoid manual header edits on compressed files. Use `bcftools reheader`, `bcftools annotate -h`, or the header update mode of the caller that produced the file. 6. Reindex after every header or body change. A stale index can mimic a header error and waste hours. 7. Store the exact commands and tool versions used for repair. A header fix that cannot be reproduced is a future incident. 8. Test the repaired VCF with the same downstream tools that will consume it. Passing a generic validator is necessary, not sufficient. ## Common Mistakes and Limitations Treating a `chr` prefix as cosmetic is a common mistake. It is a real identifier change. A `chr1` record does not match a `1` annotation, and a header edit that renames one side without the other creates a file that looks consistent but is not. Editing the `#CHROM` line by hand is another common failure. Removing a sample name from the header does not remove its genotype column from the body. The file then has more body columns than the header declares. Use `bcftools view -s` or `bcftools reheader -s` instead. Copying contig lines from an unrelated reference is a third mistake. The names may match. The lengths may not. A length mismatch can break indexing, region queries, and sequence dictionary validation. Build contig lines from the reference `.fai` or `.dict` that was actually used. Adding duplicate definitions creates a file that passes some tools and fails others. Two `##INFO` lines for `DP` with different types are worse than one correct line. Resolve duplicates by checking the body values, then keep one definition. Using `bcftools reheader` when the body is malformed is a common false fix. Reheader replaces header text. It does not validate body columns, undefined tags, or REF alleles. A file can have a perfect header and a broken body. Assuming `bcftools view` has fixed every problem is also risky. Some tools auto-add missing header lines while reading. The auto-added line may not carry the correct `Number` or `Type`. The file passes the first read and fails at the next tool. Forgetting to reindex is a trivial mistake with expensive symptoms. After `bcftools reheader`, the old `.tbi` or `.csi` file may still be present. Delete or rebuild it deliberately. Do not leave two index files with ambiguous timestamps. Limitations matter. A header repair cannot resolve a true assembly mismatch, a sample swap, contaminated DNA, or a mislabeled variant. Those require reference checks, sample identity checks, and project-specific validation. Individual projects need validation against their exact reference, caller, and downstream pipeline. A repaired VCF is not automatically a correct VCF. ## Frequently Asked Questions ### What is the fastest way to check a VCF header mismatch? Run `bcftools view -h` to inspect the header and `bcftools view -H` to list body contigs, then compare the two. This catches the most common contig naming and missing definition problems in seconds. ### Why does chr1 versus 1 cause a mismatch? Chromosome identifiers are exact strings, so `chr1` and `1` are different contigs to most parsers. A VCF using `chr1` will not match annotations or reference dictionaries that use `1` unless one side is converted. ### Can I edit a VCF header by hand? You can edit a small uncompressed header as a last resort, but hand edits often break quoting, line order, or sample columns. Use `bcftools reheader` or `bcftools annotate -h` and validate the result. ### How do I add missing INFO or FORMAT definitions? Create a header fragment with the correct `##INFO` or `##FORMAT` line and apply it with `bcftools annotate -h extra.hdr`. The `Number` and `Type` must match the values in the body. ### Why does bcftools still fail after I reheader? A reheader changes only the header. The body may still contain undefined tags, the wrong number of sample columns, or REF alleles that do not match the reference. Reindex the file and run a validator. ### Does a VCF header need every contig? Strict tools require every contig used in the body to be declared in the header, often with a length. Lenient tools may add missing lines, but that auto-repair can hide a sequence dictionary mismatch. ### How are VCF headers different from FASTA and FASTQ headers? A FASTA header labels a sequence and a FASTQ header labels a read with quality scores. A VCF header is a typed schema for contigs, tags, filters, and samples, so a VCF mismatch is a schema mismatch. ### Can I fix a VCF header mismatch without the reference genome? You can fix naming and missing tag definitions without the reference if the body is internally consistent. You cannot confirm contig lengths, REF alleles, or assembly identity without the reference, so validation remains incomplete. ## Sources 1. [Brentp/Vcfanno: Fix End In Non Vcf Files With Ref And Alt Columns](https://doi.org/10.5281/zenodo.287616)