# AlphaFold MSA Errors: How to Fix Multiple Sequence Alignment Failures Most AlphaFold MSA errors trace back to one of two root causes. Either the query sequence has too few detectable homologs, so the [multiple sequence alignment](/blog/guides/multiple-sequence-alignment) (MSA) comes back shallow or empty, or the input file is malformed and the pipeline cannot parse it. The first thing to check is always the same. Open the run log and count how many sequences the generated MSA actually contains. That single number separates mechanical failures, which stop the pipeline, from silent failures, which finish normally but produce an unreliable model. An MSA is an alignment of your query protein against its evolutionary relatives, called homologs. AlphaFold reads that alignment through its Evoformer neural network modules and extracts co-evolutionary signals, patterns of correlated mutations that arise when residues sit close together in three-dimensional space. Starve the network of homologs and it falls back on structural templates and learned priors, which is why MSA depth, the number of independent sequences in the alignment, is one of the strongest practical determinants of model quality. This guide explains how to fix an AlphaFold MSA error in practice. It works from the most common cause to the rarest, explains the mechanism behind each failure, and gives you a diagnostic sequence, concrete commands, and prevention habits. If you are new to the tool, treat this as the troubleshooting chapter that most AlphaFold tutorial material leaves out. ## What an AlphaFold MSA Error Is Really Telling You AlphaFold MSA error causes fall into two families. Hard failures stop the pipeline. You see a traceback or an error message about feature generation, a parser exception on an alignment file, a missing binary, or a database that fails to open. The run produces nothing. Soft failures are more dangerous. The run completes, files appear in the output directory, and the model looks plausible until you inspect the confidence metrics. The two metrics that matter most are pLDDT and PAE. pLDDT, the predicted local distance difference test, is a per-residue confidence score from 0 to 100, stored in the B-factor column of the output coordinates. PAE, the predicted aligned error, is a matrix that describes expected positional error between every pair of residues. For complexes, ipTM, the interface version of the predicted template modeling score (pTM), serves the same purpose between chains. A soft MSA failure usually shows up as uniformly low pLDDT across a globular domain that should fold well, or as high PAE between residues that should be rigidly connected. A third category sits between the two. The pipeline warns rather than fails, for example when a ColabFold run reports a very small number of aligned sequences. Treat warnings about shallow alignments as errors in disguise. One more distinction saves time. Low confidence in a specific loop or terminus is often not an MSA problem at all. Intrinsically disordered regions, signal peptides, and flexible linkers score poorly because they genuinely have no single structure. AlphaFold's own documentation treats pLDDT values below about 50 as likely disorder. Fixing the MSA will not change that, and misreading disorder as a pipeline bug is one of the most common time sinks in this workflow. ## How AlphaFold Builds an MSA, and Where It Breaks Every AlphaFold MSA error makes more sense once you know which search route your run uses. There are three. The open-source DeepMind pipeline searches sequence databases with iterative profile methods, which build a position-specific model of the protein family as they search. JackHMMER, part of the HMMER software package, searches UniRef90, the UniProt Reference Clusters collapsed at 90 percent sequence identity, and MGnify, the EMBL-EBI collection of metagenomic protein sequences. HHblits, from the HH-suite package, searches BFD, the Big Fantastic Database of metagenomic and reference sequences assembled for AlphaFold. Metagenomic means the sequences were sampled directly from environmental samples rather than from cultured organisms. In parallel, a template search looks for experimentally determined structures of homologs, known as templates, in the [Protein Data Bank](/blog/guides/protein-data-bank). ColabFold replaces those searches with MMseqs2, a fast sequence search method, run against a combined database of reference and environmental sequences. It can use a remote API or a local installation. The remote API is convenient and rate limited. The hosted AlphaFold Server from Google DeepMind runs its own searches on Google infrastructure. You submit sequences, and the server builds the alignment for you. Each route breaks differently. The open-source pipeline fails on database paths, corrupted downloads, and memory. ColabFold fails on input formatting and remote API limits. The server fails on submission rules, since it enforces per-job limits on combined length, entity counts, and daily quotas. Input hygiene matters on all three routes, because every route starts by parsing your FASTA file. The mechanism connecting MSA quality to model quality is co-evolution. When two residues contact each other in the folded protein, mutations at one position tend to be compensated by mutations at the other across evolution. That signal only appears when the alignment contains enough diverse but homologous sequences. A shallow MSA drowns the signal in noise, and no amount of downstream compute recovers it. ## A Five-Step Diagnostic Walkthrough ![Five-step diagnostic flow: capture the error, validate the FASTA, measure MSA depth, read the top hits, compare with confidence metrics.](/article-images/illustrations/alphafold-msa-error-diagnostic-walkthrough.webp) Work through these steps in order before changing anything. 1. **Capture the exact error text.** Distinguish a Python traceback from a warning line in the log. Copy the full message into your notes. 2. **Validate the input FASTA**, the standard plain-text sequence format. Count the records with `grep -c "^>" query.fasta` and inventory the characters with `grep -v "^>" query.fasta | tr -d "\n" | fold -w 1 | sort | uniq -c`. A clean protein file shows one header and exactly 20 residue letters, possibly with X for unknown positions. Digits, asterisks, spaces inside the sequence line, or unintended lowercase letters all need fixing before you touch anything else. 3. **Measure MSA depth.** If the run produced an A3M or Stockholm alignment (the two alignment formats these tools exchange), count the headers with `grep -c "^>" msa.a3m`. If the run died before writing an alignment, the log usually states the failure stage. 4. **Inspect what the search actually found.** Open the alignment and read the header annotations of the top hits. A healthy MSA for a bacterial enzyme shows hits across many genera with a smooth spread of identity. An MSA full of copies of your own construct, or full of unrelated proteins, explains a bad model faster than any score. 5. **Read the confidence metrics against the MSA.** Deep MSA with low pLDDT points to disorder, oligomeric state, or domain problems rather than alignment depth. Shallow MSA with low pLDDT is the classic case for the fixes below. Most AlphaFold tutorial material stops at a successful submission, so run this diagnostic pass whenever a result looks wrong, not only when the pipeline crashes. ## Troubleshooting Table: Symptoms, Causes, and Fixes The table collects the recurring failure signatures, ordered roughly from most to least common. Each row pairs a symptom with the solution that holds up in production runs. | Symptom | Likely cause | How to confirm | Fix | |--|--|--|--| | Pipeline stops at feature generation with a parsing or "no sequences" message | Malformed input FASTA | Run the alphabet check from the walkthrough | Rewrite the FASTA with standard residues and a simple header | | Alignment comes back empty or nearly empty | No detectable homologs in the searched databases | Count MSA headers, check the log for the databases searched | Expand database scope, add metagenomic searches, see Fix 2 | | Run completes but pLDDT is low across a folded domain | Shallow MSA starving the Evoformer of co-evolutionary signal | Compare MSA depth against the confidence metrics | Apply the shallow MSA fixes, add templates if available | | Parser error when supplying a custom A3M or Stockholm file | Format defect such as Windows line endings or a missing terminator | Open the file in a plain text editor, run esl_reformat | Convert formats, fix line endings, see Fix 4 | | Out of memory error during inference | MSA too deep or chain too long for available memory | Crash correlates with long chains or deep alignments | Reduce MSA cluster and extra sequence settings, see Fix 6 | | Multimer run gives low interface confidence | Unpaired MSA or wrong stoichiometry | Check ipTM and interface PAE, verify chain copies | Correct stoichiometry, enable MSA pairing, see Fix 5 | | MSA contains many unrelated proteins | Contaminated query, affinity tags, or low-complexity regions | Read annotations of the top MSA hits | Clean the sequence, split domains, see Fix 1 | | ColabFold remote search fails or hangs | MMseqs2 API rate limit or outage | Retry after a delay, check service status | Run a local MMseqs2 search or fall back to JackHMMER databases | | Errors about missing binaries or checksum mismatches during setup | Incomplete database download or PATH problem | Run `which jackhmmer`, verify checksums | Re-download, activate the correct environment, see Fix 3 | | AlphaFold Server rejects the submission | Per-job limits on length, entities, or daily quota | Read the exact rejection message on the server | Trim the construct, split the complex, wait for quota, see Fix 7 | ## Fix 1: Clean the Input Sequence Input defects are the cheapest cause to fix and the most common reason a run dies before the search even starts. Start with the container. A valid FASTA record looks like this. ``` >my_protein wild-type construct MKTAYIAKQRQISFVKSHFSRQ ``` The header starts with a greater-than sign, sits on its own line, and the sequence follows on the next line. Common defects include copy-pasted web page artifacts, residue numbers pasted between residues, headers that lost their greater-than sign, and files saved with word processor formatting. Open the file in a plain text editor, never a word processor. Then check the alphabet. Standard AlphaFold inputs use the 20 standard amino acids. Most pipelines either reject non-standard letters or convert them to X, and X cannot participate in profile matches, which quietly degrades the search. Selenocysteine, written U, is a cysteine homolog, so replacing it with C is standard practice before searching. Ambiguous codes such as B, Z, and X should be minimized. Runs of X from unknown sequencing regions can be trimmed if they fall outside the domain you care about. Lowercase letters are legal in some formats but carry meaning in A3M, where they mark insertions, so keep query files uppercase. Remove expression artifacts. Affinity tags such as polyhistidine tails, linker peptides, and any fusion partner left over from the cloning strategy will dominate the MSA search if they are long enough, pulling in unrelated sequences and diluting the alignment. Model the tag-free construct unless the tag itself is the subject of study. Watch for annotation artifacts. A gene model with a frameshift or a premature stop produces a truncated or garbled query that finds few homologs. If a supposedly conserved protein returns a shallow MSA, compare your sequence against the reference transcript or genome. A single wrong residue in the middle of the reading frame is enough to break everything downstream of it. Finally, decide deliberately about signal peptides and transmembrane segments. Keep them if you want full-length context, remove them if you are modeling a soluble domain, and record the choice. Inconsistent construct boundaries between runs are a frequent source of confusing comparisons. ## Fix 2: Rescue a Shallow MSA ![Decision path for a shallow MSA: expand databases, switch search engines, split domains, or fall back to single-sequence prediction.](/article-images/illustrations/alphafold-msa-error-shallow-msa-route.webp) A shallow MSA is the classic soft failure. The run finishes, but the Evoformer had too little co-evolutionary signal to work with, and confidence suffers. A recent review of AI-driven structural biology puts this precisely, noting that prediction reliability depends on MSA depth rather than on the taxonomic composition of the Protein Data Bank, which means the fix is more homologs, not closer structural relatives [1]. There is no universal cutoff for enough sequences, because difficulty varies with fold and length. As working guidance, alignments with only a few dozen sequences are a warning sign, alignments with thousands are comfortable, and the confidence metrics are the final judge. Work through these options in order. **Expand the database scope.** The default monomer search against UniRef90 alone misses homologs that live in metagenomic data. The full database preset of the open-source pipeline adds BFD and MGnify, which routinely multiplies alignment depth for environmental and poorly cultivated lineages. If disk or memory is tight, adding MGnify alone often captures most of the gain at a fraction of the size. **Switch search engines.** ColabFold's MMseqs2 mode against the combined reference and environmental database, selected with the msa_mode option set to mmseqs2_uniref_env, often finds homologs that iterative HMMER searches miss, and the reverse is also true. Running both searches and merging the alignments is a legitimate strategy. **Tune the search itself.** Additional JackHMMER iterations build a richer profile, and modestly relaxed reporting thresholds can pull in remote homologs. Validate every relaxation by reading the top hits, because a threshold set too loose fills the alignment with unrelated proteins, which is worse than a shallow MSA. **Use templates when they exist.** A structural template from the Protein Data Bank can carry a prediction when the MSA is weak. Keep the template date filter sensible for your question, and remember that a template-based model inherits the template's conformational state. **Split multidomain queries.** A long, multidomain query dilutes the per-domain signal, because each domain sees a shallower effective alignment. Split at linkers, predict domains separately, and assemble with the PAE matrix as a guide. **Question the query.** Orphan status is sometimes an annotation artifact. Verify the reading frame, check for sequencing errors, and confirm the protein is real before concluding it is novel. For genuinely orphan proteins, those lacking detectable homologs, single-sequence prediction modes exist, and language model methods such as ESMFold were built for exactly this case. Expect reduced accuracy, especially at interfaces, and treat the output as a hypothesis. ## Fix 3: Repair Databases, Binaries, and Environments Mechanical failures during setup or search usually have boring causes, which is good news. Check the binaries first. The open-source pipeline needs HMMER and HH-suite tools on the PATH. ``` which jackhmmer which hhblits ``` A missing result means the conda environment is not active, the container image is wrong, or the installation step was skipped. Check the databases. A database file that failed to download completely produces errors at search time or, worse, silently truncated results. Compare file sizes against the published values, verify each checksum, a short fingerprint computed from the file, against the values distributed with the release, and re-download anything that fails. The full database set occupies multiple terabytes, so confirm free space and bandwidth before starting. The reduced database preset exists for testing and small-scale work, and predictions from it are correspondingly weaker. Check versions. Database releases update on their own schedules, and mixing a new index with an old binary, or a new code version with old cached features, produces confusing behavior. Pin the versions of the code, the binaries, and the databases together, and record them with your results. Check the environment, not just the tool. Python environment conflicts, mismatched CUDA versions for GPU runs, and stale cached features from a previous failed run all masquerade as MSA errors. When a run fails oddly, delete the features directory for that job and rerun from scratch before debugging deeper. **Safety note:** database downloads are large enough that interrupted transfers are routine. Verify checksums before use, because a corrupted database produces wrong results that look like ordinary shallow alignments. ## Fix 4: Validate Custom Alignments Supplying your own alignment gives you control, and it gives you a new file format to get wrong. ColabFold accepts custom MSAs in A3M format, and HMMER-based tools exchange alignments in Stockholm format. A3M looks like FASTA with one rule. Residues in columns aligned to the query are uppercase or gaps, and insertions relative to the query are lowercase. ``` >query MKTAYIAKQR >homolog_one MKTAYIAKQR >homolog_two mktayia---AYIAKQR ``` In homolog_two, the lowercase block at the start is an insertion relative to the query, the three dashes align to the start of the query, and the remaining uppercase residues match. The query line itself must be uppercase and gap-free. Stockholm files begin with a format declaration line, carry annotation blocks prefixed with hash marks, and end with a double slash terminator. Missing that terminator is a classic error, as are Windows line endings. ``` dos2unix msa.a3m ``` Line ending problems produce parser errors that never mention line endings, so normalize first whenever a file was touched on Windows. Validate before you submit. ``` esl_reformat afa msa.sto > msa.fasta ``` The esl_reformat utility ships with HMMER and refuses to read a malformed Stockholm file, which makes it a cheap validator. The reformat.pl script from HH-suite converts between alignment formats, including A3M. Then sanity check the content. The first sequence must be your query, exactly as you want it modeled. Headers should be unique, and if you want ColabFold to pair chains by organism for multimer work, the headers must carry usable organism identifiers. Remove exact duplicates, remove fragments that cover only a sliver of the query, and confirm column count consistency across records. A quick way to spot a truncated record is to count characters per line and look for outliers. One caution covers all custom alignments. An MSA you built with different settings is a different input, so archive the exact file you fed to the model alongside the output. ## Fix 5: Fix Multimer and MSA Pairing Failures Complex predictions add a second alignment problem on top of depth. AlphaFold-Multimer wants paired MSAs, alignments in which homologs of the different chains that come from the same organism are matched row by row. Paired rows give the network inter-chain co-evolutionary signal, which is the strongest evidence it gets for interface geometry. Unpaired alignments still work, but interface accuracy drops, and the model leans on learned priors instead. The signature of a pairing failure is a model where each chain looks fine on its own but the complex scores poorly. Check ipTM and look at the PAE block structure between chains. High PAE between chains, with low PAE inside each chain, means the model is confident about the parts and lost about the assembly. Fix stoichiometry, the count of copies of each chain, first. Homo-oligomers need one input copy per chain, so a homodimer needs the same sequence entered twice. This surprises people, because the instinct is to submit each unique sequence once. Heteromers need every distinct chain, in the order you intend. Then fix pairing. ColabFold pairs chains by organism when the MSA headers carry taxonomy information, which happens automatically with its own database searches. If you supply a custom MSA, make sure headers preserve organism identifiers, or pairing will silently fail. Verify that the search actually found homologs for every chain, because a chain with an empty MSA drags the whole interface down. Run the multimer preset with its default multiple predictions per model and compare, because interface predictions vary more than single-chain predictions between seeds, the random starting points of the network's sampling. If every seed agrees on a low ipTM, take the result seriously. Some candidate complexes are genuinely weak, transient, or dependent on a missing component such as a cofactor or a third protein. Applied work leans on this heavily. Reviews of AlphaFold applications highlight host-pathogen protein interaction prediction as a flagship use case, and interface quality in exactly those settings is where shallow or unpaired MSAs do the most damage [1]. ## Fix 6: Free Memory When the MSA Is Too Deep Deep alignments and long chains both inflate memory use during inference, and the failure mode is abrupt. You get an out of memory error from the accelerator runtime, or the process is killed by the operating system. The main levers, in order of impact. **Reduce the MSA the model actually sees.** The model configuration exposes max_msa_clusters, the number of alignment rows sampled for the main representation, and max_extra_msa, the number of additional rows used for the extra MSA stack. Cutting both, for example to 64 clusters and 128 extra sequences as a starting point, sharply reduces memory at a modest accuracy cost. ColabFold exposes the same control as its max_msa option. **Crop the construct.** Modeling the folded domains separately, rather than one long chain with flexible regions, reduces memory sharply, because attention costs grow with the square of the length. This is often the difference between a run that fits and one that does not. **Use fewer models and seeds.** The multimer preset runs five predictions per model by default, and each one is independent. For a memory-limited debugging pass, run one model first, then scale out once the settings work. **Recycle less.** Recycling, the repeated application of the network to its own output, defaults to about three cycles in most configurations. Reducing recycles mainly saves time rather than peak memory, so reach for the MSA and length levers first. **Skip relaxation during debugging.** Relaxation, the optional physical refinement step at the end, occasionally fails on models with severe clashes. It is safe to skip it while debugging and apply it later to the final model. **Safety note:** on shared clusters, run memory-heavy jobs through the scheduler rather than on login nodes. A job that grabs all of a login node's memory gets killed, and takes other users' work with it. ## Fix 7: AlphaFold Server Errors and Quotas The hosted AlphaFold Server from Google DeepMind removes the installation burden and adds submission rules. When a submission fails, the server tells you which rule you hit. The common rejections are caps on total combined length across all chains, caps on the number of entities such as proteins, [nucleic acids](/blog/guides/nucleic-acids), ligands, and ions, and a daily job quota per user. The exact numbers change as the service evolves, so read the current limits in the official documentation rather than relying on secondhand figures. A construct that just barely exceeds a limit is fixed by trimming unstructured termini or modeling domains separately. The server builds its own MSA and does not accept uploaded alignments. If your workflow depends on a custom MSA, for example a curated alignment for a protein family, use ColabFold or the open-source pipeline instead. Conversely, if the server's automatic search returns a shallow alignment, the fixes are the ones from Fix 2 applied to the input, mainly checking the sequence and considering whether a local run with expanded databases is the better tool. Server runs also fail for mundane reasons. Expired sessions drop long forms, unsupported molecule types are rejected at validation, and results expire after a retention period, so download outputs promptly. **Safety note:** submitting sequences to any public web service moves data outside your control. Review the terms of service and your institution's data policies before uploading unpublished sequences, especially for patent-related or collaborative projects with data sharing agreements. ## Common Mistakes and Limitations These are the errors people make after the pipeline stops throwing errors. **Treating a completed run as a successful run.** Files in the output directory prove nothing. Read pLDDT and PAE before you interpret anything. **Deleting the alignment files to save space.** The MSA is the primary evidence behind the model and the cheapest way to rerun inference after a configuration change. Archive it with the coordinates. **Reading MSA depth as a guarantee.** A deep alignment improves the odds, but domain swapping, wrong oligomeric states, and convergent evolution still produce confident-looking wrong models. Depth is a risk factor, not a certificate. **Confusing the confidence metrics.** pLDDT is per residue, pTM is a global score for the chain, and ipTM applies to interfaces. Comparing a pLDDT value against an ipTM interpretation leads to wrong conclusions about which part of the model failed. **Trimming low pLDDT regions and rerunning without asking why they scored low.** If the region is a predicted disorder segment, trimming is a modeling decision worth documenting. If it is an expression tag, trimming is input hygiene. The fix differs. **Blaming the model when the MSA changed between runs.** Comparisons across runs are only valid when the alignment is held fixed. **Concluding failure from a single seed and a single model.** Run the full model set, or at least multiple seeds, before deciding a target failed. **Forgetting what the model is.** A prediction is a static snapshot, usually of an apo state, meaning no ligand bound. Reviews of AI-driven drug and vaccine design caution that direct [molecular docking](/knowledge/bioinformatics/docking-algorithms-autodock-glide-and-beyond) into predicted structures, without refinement or experimental validation, is unreliable precisely because of those apo conformations [1]. Low confidence at a binding site is often the model telling you the site is flexible. And the honest limitation that no command fixes. Some proteins are intrinsically disordered or fold only upon binding. No MSA repair produces a single confident structure for a chain that has none, and recognizing that outcome is a result, not a failure. ## Prevention Practices A few habits prevent almost every recurrence. **Curate input with a fixed checklist.** Alphabet check, tag removal, header hygiene, construct boundaries. Thirty seconds of checking beats an hour of debugging. **Record MSA depth with every prediction.** Store the alignment file, the database versions, the search settings, and the sequence count next to the coordinates. As applied fields move from empirical trial-and-error toward rational in silico design, the provenance of each model becomes part of the scientific record, and the MSA is the part of that record most often lost [1]. **Pin versions.** Code, binaries, databases, and the exact command line belong in a small text file in the results directory. Reproducing a number six months later depends on it. **Benchmark with a positive control.** Run one protein with a known structure and a deep MSA through your pipeline whenever you update anything. A control that suddenly degrades tells you the environment changed before your real targets do. **Automate the diagnostics.** The five-step walkthrough fits in a short shell script that validates the FASTA, counts alignment headers, and greps the log for the search stage. Run it after every pipeline update. **Match the route to the question.** Quick interactive work belongs on ColabFold or the server. Curated alignments, custom databases, and sensitive sequences belong on a local installation. Choosing the right route up front avoids most quota and format failures entirely. ## Frequently Asked Questions ### What causes an AlphaFold MSA error? Most often a query sequence with too few detectable homologs, or a malformed input file the pipeline cannot parse. Count the sequences in the generated alignment and validate the FASTA before changing anything else. ### How many sequences does an MSA need for a reliable AlphaFold model? There is no universal cutoff. Judge by the pLDDT and PAE confidence metrics on your actual protein, since the depth a domain needs varies with its size and fold. ### Can AlphaFold predict a structure without an MSA? Yes, in single-sequence modes, but accuracy drops noticeably, especially for interfaces and remote folds. Language model tools such as ESMFold are usually the better choice for orphan proteins. ### Why is my MSA empty when my protein has obvious homologs? Usually the input file, the database scope, or the query itself. Check FASTA formatting, confirm which databases the run actually searched, and verify the sequence is not truncated or frameshifted. ### How do I fix a malformed A3M file? Normalize line endings, keep the query first and uppercase, write insertions in lowercase, give every record a unique header, and validate the file with esl_reformat before submitting it. ### Does a deep MSA guarantee an accurate structure? No. Depth improves the odds substantially, but disorder, domain swaps, and incorrect oligomeric states still occur. Read the confidence metrics rather than the alignment size alone. ### Can I upload a custom MSA to the AlphaFold server? No. The hosted server builds its own alignment automatically. For custom MSAs, use ColabFold or the open-source pipeline on your own hardware. ### Why does ColabFold find homologs when my local AlphaFold install does not? Different search engines and database scopes. ColabFold's MMseqs2 mode searches a combined reference and metagenomic database, while a minimal local setup may search UniRef90 alone. Expand the local databases or merge both searches. ## Sources 1. [From Sequence to Structure: AlphaFold and the AI Revolution in Aquaculture Drug Discovery and Vaccine Design.](https://pubmed.ncbi.nlm.nih.gov/42861495/)