pVACseq's "wildtype amino acid sequence mismatch" error: what's actually happening and how to fix it

By Lociven · NeoantigenLab · July 2026

pVACseq's "wildtype amino acid sequence mismatch" error: what's actually happening and how to fix it

If you run pVACseq long enough, you will eventually hit this:

ERROR: There was a mismatch between the actual wildtype amino acid sequence (Y) and the expected amino acid sequence (P). Did you use the same reference build version for VEP that you used for creating the VCF?

It's one of the most-reported problems in the pVACtools GitHub issue tracker — it recurs across multiple issues (#101, #150, #368, #571, #731, #790), spanning years of the tool's history. Most write-ups either restate the error or hand-wave "check your reference build." Here's what's actually happening under the hood, reproduced against the real code path, plus the exact fix.

Where it comes from

The check lives in pvactools/lib/fasta_generator.py, line 264:

if wildtype_amino_acid != '-' and wildtype_amino_acid != wildtype_subsequence[start:end]:
    sys.exit("ERROR: There was a mismatch...")

pVACseq computes the wildtype residue two different ways and expects them to agree:

Value Where it comes from VEP CSQ field
Expected wildtype residue Computed from the genomic REF/ALT allele Amino_acids (e.g. P/A → P)
Actual wildtype residue Read from the translated Ensembl transcript WildtypeProtein

When these two disagree, it means the reference genome used to call your variants and the Ensembl reference VEP used to annotate them are not the same. pVACseq has no way to reconcile that, so it exits hard rather than silently generating a wrong peptide.

What actually causes the mismatch, in practice:

  • Variants called against GRCh37 but annotated with a GRCh38 VEP cache (or vice versa)
  • VEP cache / Ensembl release version drift — transcript sequences get revised between releases
  • Transcript version drift — ENST00000332831.4 vs .5 vs .8
  • Mixed reference FASTA sources (UCSC-style chr1 contigs vs Ensembl-style 1)

Reproducing it for real

We installed pVACtools 7.0.1 and ran it against the package's own public example VCF (HCC1395 cell line, 1,470 variants, already VEP-annotated). The baseline run is clean — exit 0, 1,902 FASTA records.

A genuine build/version mismatch requires re-annotating with a different VEP cache, which means a 15GB+ download just to trigger one error message. Instead, we reproduced the actual data state a mismatch produces — a transcript's WildtypeProtein residue disagreeing with the allele-derived residue — directly in the same code path. One variant (chr1:686483, transcript ENST00000332831.5, gene OR4F16) had its expected wildtype residue at protein position 58 swapped from P to Y. Running generate_protein_fasta against that state reproduces the exact error and traceback:

EXIT CODE: 1
ERROR: There was a mismatch between the actual wildtype amino acid sequence (Y) and the expected amino acid sequence (P)...
File "fasta_generator.py", line 264, in execute

The fix that's actually verified to work

The vatools package ships a purpose-built tool for exactly this: ref-transcript-mismatch-reporter.

Step 1 — diagnose (soft mode): flags mismatched variants without removing anything.

ref-transcript-mismatch-reporter mismatch.vcf -f soft -o soft.vcf
→ Total variants with mismatched annotations: 1 (0.27% of processable)

Step 2 — clean (hard mode): removes the mismatched variants.

ref-transcript-mismatch-reporter mismatch.vcf -f hard -o cleaned.vcf
→ 1,470 variants → 1,469 (1 removed)

Step 3 — verify: re-run FASTA generation against the cleaned VCF.

EXIT CODE: 0 — no mismatch error, 1,900 records (baseline 1,902 minus the 2 WT/MT records for the removed variant)

This confirmed clean in our test run: the exact problem transcript was gone, no new errors introduced, and the record count dropped by precisely the expected amount.

The real fix is upstream of this, though. ref-transcript-mismatch-reporter is a practical filter for a small number of residual mismatches — it doesn't fix the root cause. If mismatches are widespread, re-annotate with a VEP cache that matches the build and Ensembl release used to call your variants in the first place, and make sure --assembly/--fasta in your VEP run matches your alignment reference.

Get the protocol

NeoantigenLab Protocol Pack — pVACseq Step-by-Step ($29)

This error and five others we've hit are covered in the full pVACseq protocol — exact commands, the reference/VEP version-matching checklist, and the correct -e1 flag syntax most guides get wrong.

Get the Protocol Pack →

Tags: pVACseq, wildtype sequence mismatch, VEP, reference genome build, neoantigen prediction, troubleshooting, bioinformatics, fasta_generator

댓글

댓글 쓰기

이 블로그의 인기 게시물

What Is a Neoantigen? A Practical Guide for Experimental Researchers

By Lociven · NeoantigenLab · July 2026 If you work in cancer immunology, you have heard the word neoantigen more times than you can count. It appears in grant proposals, immunotherapy papers, and tumor board discussions. But the explanations are usually either too shallow ("mutated peptides the immune system can recognize") or buried in computational methods papers that assume you already know what a VCF file is. This post is for the wet-lab side of the room — the researchers who understand tumor biology and immunology but want a clear picture of what neoantigens are, where they come from, and why the field cares so much about them. Figure 1. Most somatic mutations do not become immunogenic neoantigens. Each step — coding region, MHC binding, processing, T cell recognition — acts as a filter. The core idea A neoantigen is a peptide fragment, derived from a tumor-specific somatic mutation, that can be presented on the surface of a cancer cell via MHC molecule...
자세한 내용 보기

NetMHCpan Explained: How MHC Binding Prediction Works and How to Read the Output

By Lociven · NeoantigenLab · July 2026 You run NetMHCpan on your mutant peptide list and get back a table full of percentile ranks, EL scores, and BA scores. One peptide shows 0.48% rank. Another shows 2.1%. What does that mean, and which one should you follow up on? NetMHCpan is the most widely used MHC-I binding prediction tool in neoantigen research. Most papers cite it, most pipelines include it, and most wet-lab researchers who encounter its output don't fully understand what it's predicting. This post explains the model, the output, and where interpretation goes wrong. What NetMHCpan predicts NetMHCpan predicts the binding affinity between a peptide and an MHC class I molecule. More precisely, it predicts two things: Binding affinity (BA) : Estimated IC50 in nM — the concentration of peptide needed to displace 50% of a reference ligand from the HLA molecule. Lower IC50 = stronger binder. The common threshold is IC50 < 500 nM for "weak binder,...
자세한 내용 보기

Tumor Mutational Burden (TMB): What It Measures, What It Doesn't, and How to Interpret It

By Lociven · NeoantigenLab · July 2026 Your pathology report comes back with a TMB of 14 mut/Mb. The oncologist asks whether this patient is likely to respond to pembrolizumab. What do you actually say? Tumor mutational burden has become one of the most frequently cited biomarkers in solid tumor immunotherapy — and one of the most frequently misunderstood. This post explains what TMB measures, how it is calculated, what the FDA approval actually covers, and what it cannot tell you. What TMB measures — and what it doesn't TMB is a count of somatic mutations per megabase of coding sequence sequenced. That is all it is. It does not measure: Whether any of those mutations produce peptides that bind HLA Whether those peptides are actually presented on tumor cell surfaces Whether the patient has T cells that recognize them Whether the tumor microenvironment is immunologically accessible TMB is a proxy. More mutations → more potential neoantigens → higher p...
자세한 내용 보기