# Troubleshooting UniProt Annotation Gaps You look up a protein in UniProt and the Function section is empty. There are no GO terms, no keywords, no domains listed, or the whole entry looks like a bare sequence with an accession number. The most common cause, by a wide margin, is that the entry is unreviewed, meaning it sits in TrEMBL rather than the manually curated Swiss-Prot section of UniProtKB, and no automatic annotation rule has matched it yet. The first thing to check is the entry status badge at the top of the entry page: if it says "Unreviewed," most downstream questions answer themselves. This guide walks through every major cause of missing annotation in UniProt, from the routine to the obscure, gives you a diagnostic sequence you can run in under ten minutes, and shows the exact commands and tools that fix each failure mode. It assumes you are working with protein accessions, FASTA files, and a terminal, and it treats UniProt documentation as the reference standard for how the database is supposed to behave. ## What an annotation gap actually is Before troubleshooting, separate three situations that look identical on the surface but have different fixes. **True annotation gap.** The entry exists, the sequence is correct, and UniProt simply has no evidence for function, localization, or domains. The gap is real and reflects the state of knowledge about that protein. **Search failure.** The annotation exists, but your query missed it. You searched a gene symbol that UniProt stores differently, queried a field that does not exist, or used an obsolete accession. The data was there the whole time. **Format and interface failure.** The data exists but arrived in a form you did not expect: a field you requested in the REST API is empty, a TSV download truncated a column, or a saved query from a previous release no longer matches anything. Distinguishing these three at the start saves hours. The diagnostic sequence below does that, and the troubleshooting table maps each symptom to its cause and fix. ## Start here: the five-minute diagnostic ![Path that tells a true annotation gap apart from a search failure and a format failure, ending in the right fix.](/article-images/illustrations/uniprot-missing-annotation-troubleshooting-gap-triage.webp) Run these checks in order. Each one narrows the field. 1. **Paste the accession directly into uniprot.org.** If the entry does not resolve, you have an identifier problem, not an annotation problem. Skip to the identifier mismatch section. 2. **Check the entry status.** Reviewed entries carry manual annotation from UniProt curators. Unreviewed entries carry only automatic annotation and literature references picked up by automated systems. 3. **Check the Protein existence line.** UniProt assigns each entry a level from 1 to 5: level 1 means evidence at the protein level, level 2 means evidence at the transcript level, level 3 means inference by homology, level 4 means prediction, and level 5 means the existence is uncertain. A level 4 or 5 entry will rarely carry rich functional annotation. 4. **Check the evidence tags.** Every annotation line in UniProt carries evidence labels such as "Experimental evidence at protein level," "By similarity," or "Imported from an automated annotation rule". Look at how existing annotations are supported before assuming the missing ones were lost. 5. **Check the sequence length and fragment status.** A line in the header reading "Fragment" means the sequence is partial, which alone can block annotation rules that require full-length matches. 6. **BLAST the sequence against Swiss-Prot only.** Use the UniProt BLAST interface and restrict the target database to Swiss-Prot. A strong hit to a reviewed entry with the same family tells you whether homology-based annotation is feasible. If step 2 shows "Unreviewed" and step 3 shows level 3 or 4, you are looking at the standard state of most entries in UniProtKB. The fixes below describe what to do about it. ## Core troubleshooting table | Symptom | Likely cause | How to confirm | Fix | |--|--|--|--| | Search returns no entry at all | Obsolete or wrong accession, gene symbol mismatch, or entry merged into another | Paste the accession directly, use the ID mapping tool | Map the identifier, search by sequence with BLAST, or search by full protein name | | Entry exists, Function section empty | Unreviewed TrEMBL entry where no automatic rule matched | Check the Reviewed/Unreviewed badge | BLAST against Swiss-Prot, run InterProScan, transfer annotation by orthology with explicit caveats | | Entry has domains but no GO terms | No InterPro or UniRule signature mapped to the sequence | Check the Cross-references section for InterPro/Pfam lines | Run InterProScan locally and map InterPro signatures to GO using InterPro2GO | | Annotation says "By similarity" | Annotation propagated from a characterized homolog, no direct experiments on this protein | Read the evidence tag on each line | Treat as provisional, verify against primary literature for the homolog | | Several entries match one gene name | Isoforms, strain variants, or a non-redundant proteome has not been selected | Check the proteome and gene fields on each entry | Filter by organism, proteome completeness, and the representative proteome set | | Entry flagged "Fragment" | Partial sequence from genome assembly or transcript evidence | Check the header line and sequence length | Search for a longer isoform, check Ensembl or RefSeq for the full coding sequence | | Annotation present yesterday, gone today | Curation update, entry merge, or rule removal in a release | Compare entry version and sequence version history on the entry page | Use the versioned archive or re-derive the annotation yourself | | API returns fewer fields than the website shows | Field parameter misspelled or changed, wrong content type requested | Request one entry as .txt and compare with your TSV output | Fetch the full flat file, then extract fields programmatically | | GO terms present but keywords missing | Keywords are curated separately and do not always track GO | Compare the Keywords and GO sections on the entry | Do not treat keywords as a subset of GO, query each independently | | Cross-references to PDB or AlphaFold missing | No published structure for the protein | Check the Cross-references section | Model the structure with a tool such as AlphaFold databases only if a modeled structure exists for the organism | ## Cause one: the entry is unreviewed This is the cause behind the majority of uniprot missing annotation questions, so it comes first. ### The mechanism UniProtKB has two sections. Swiss-Prot contains entries reviewed by human curators who read literature, assign protein names, describe function, add GO terms, keywords, features, and cross-references. TrEMBL contains everything else: entries generated from Ensembl, RefSeq, and other source databases, processed automatically with computational analysis but no curator reading papers. UniProt documentation is explicit that TrEMBL entries receive automatic annotation through systems such as UniRule and ARBA, which apply rules derived from curated families, and through similarity-based transfer. The scale asymmetry is the point. TrEMBL holds hundreds of millions of entries, while Swiss-Prot holds hundreds of thousands. For any newly sequenced organism, most of its proteome lands in TrEMBL, and a large fraction of those entries will show little beyond the sequence, a predicted protein name from the submitting pipeline, and whatever the automatic rules produced. ### What you will see An unreviewed entry typically has: - A generic name such as "Uncharacterized protein" or a name copied from the submitting nucleotide record - No Function section text - GO terms only if an automatic rule or InterPro mapping fired - An existence level of 3 (inferred by homology), 4 (predicted), or 5 (uncertain) - Evidence tags reading "Imported" or "Predicted" rather than "Experimental" ### How to fix it You cannot make UniProt curate the entry faster, but you can build defensible annotation yourself. 1. **BLAST against Swiss-Prot.** Open the UniProt BLAST tool, paste the sequence, and select Swiss-Prot as the target database. Look for hits below roughly 30 percent identity over most of the protein with a credible E-value before you consider any transfer, and look for far higher identity, above 60 to 70 percent over the full length, before you consider direct function transfer. 2. **Run InterProScan locally** on your protein set. InterProScan scans sequences against member databases including Pfam, SMART, PROSITE, and others, and reports signatures plus associated GO terms where mappings exist. A hit to a well-characterized Pfam domain often explains most of the protein. 3. **Check for orthology with a dedicated tool.** eggNOG-mapper assigns orthologous groups and transfers functional categories from precomputed orthology clusters. Orthology transfer is more reliable than best-hit BLAST because it uses gene trees and reciprocal information rather than single-pair similarity. 4. **Record your evidence chain.** Whatever you transfer, note the source entry, the identity percentage, the method, and the fact that the transfer is computational. UniProt itself marks similar transfers as "By similarity" rather than presenting them as fact, and your downstream users deserve the same transparency. ## Cause two: identifier mismatch and the entry that was never lost The second most common cause is not a gap at all. The annotation exists, but the query failed. ### The mechanism UniProt stores gene names, protein names, and identifiers in specific fields with specific rules. A gene symbol you took from a paper, an older genome annotation, or a different database may map to a different UniProt field, may be a synonym UniProt does not list, or may correspond to multiple entries. Adding to this, accessions are sometimes merged into other entries or retired, and any pipeline that cached accessions years ago can silently break. ### The diagnostic and fix 1. **Search by exact gene field, not free text.** UniProt field search supports `gene:SYMBOL` for gene names. Free text search behaves differently from field search and will match substrings across many fields, which produces false negatives and false positives in both directions. 2. **Use the ID mapping tool.** Paste a list of identifiers from NCBI Gene, Ensembl, RefSeq, PDB, or dozens of other databases, choose the target as UniProtKB, and let UniProt resolve the mapping. This is the correct answer to almost every "how do I get from gene name to UniProt entry" question. 3. **Search by sequence.** When the name is unreliable, BLAST the sequence against UniProtKB. Sequence is the ground truth and survives every naming convention change. 4. **Check whether the accession was merged.** If a retired accession is typed into the search bar, UniProt usually reports the superseding entry. If you see a redirection notice, update your records permanently, because the old accession will eventually stop resolving. A worked example in query form. To find the human BRCA1 entry by gene field rather than free text: ``` https://rest.uniprot.org/uniprotkb/search?query=gene:BRCA1+AND+organism_id:9606&format=tsv&fields=accession,id,protein_name ``` Restricting by `organism_id` with the NCBI taxonomy identifier, 9606 for human, prevents mouse and rat entries from crowding the result. ## Cause three: no annotation rule matched the protein Even in reviewed entries, entire annotation types can be absent while others are present, and the reason is usually that no rule covered the protein. ### The mechanism UniProt generates much of its automatic annotation from signature libraries and expert rules. UniRule and ARBA apply curated rules derived from protein families and align relevant annotations to proteins matching the rule conditions. InterPro signatures drive many GO term mappings through the InterPro2GO mapping maintained with the Gene Ontology Consortium. If a protein belongs to a family for which no curated signature exists, or its sequence diverged enough that no signature matches, none of these systems produce anything. The entry is not broken. There is simply no rule that fires on it. This explains a pattern that confuses many users: the entry shows a Pfam domain cross-reference but no GO terms, or has subcellular localization keywords but no molecular function. Each annotation type comes from a different source with different coverage. ### How to confirm and fix 1. **Compare signature coverage.** Open the Cross-references section and check what InterPro, Pfam, PROSITE, and other member database lines appear. If InterPro reports nothing, rule-driven GO mapping will be empty, and that is expected. 2. **Run a profile HMM search.** If InterProScan found weak or no signatures, build a hidden Markov model from a manually curated [multiple sequence alignment](/blog/guides/multiple-sequence-alignment) of the family using HMMER, and search your sequences against it. Custom HMMs routinely detect remote family membership that signature libraries miss. 3. **Lower your expectations for remote homologs honestly.** If the best characterized homolog shares only 25 percent identity, any functional transfer is a hypothesis. Write it down as a hypothesis in your results, not as annotation. ## Cause four: non-model organisms and proteome-level gaps Whole organisms can appear under-annotated in UniProt relative to what their genome papers claim. ### The mechanism Annotation in UniProt reflects what has been submitted and curated, not what is true biologically. A newly sequenced species enters UniProtKB through automated pipelines, and its entries are unreviewed until someone curates them. Genome projects also differ in proteome completeness: UniProt marks proteomes as complete or not, based on the underlying assembly and annotation quality. A draft assembly produces fragmented predictions, and fragmented predictions produce the fragment-flagged, rule-less entries described above. There is also a genuine biological component. Some proteins really are lineage-specific, with no detectable homolog outside a narrow taxonomic group. For those, no amount of BLASTing against Swiss-Prot helps, because the information does not exist anywhere yet. ### How to fix it 1. **Restrict your search to the correct proteome.** Use the proteome identifier in your query, for example `proteome:UP000005640` for the human reference proteome, so you are comparing like with like. 2. **Prefer entries linked to a complete, reference or representative proteome** when you have a choice among redundant entries for the same protein. 3. **Annotate from the genome yourself when the field is thin.** For a new genome, run a pipeline such as Bakta or Prokka for structural annotation, then InterProScan and eggNOG-mapper for functional annotation, and treat UniProt as one input among several, including RefSeq annotations at NCBI. 4. **Contact curation through the entry page** if you have experimental evidence. UniProt accepts community submissions, and experimental data you submit becomes the level 1 evidence that upgrades an entry for everyone. ## Cause five: fragments, isoforms, and sequence conflicts Some gaps trace to the sequence itself rather than to curation. ### Fragments Entries flagged as Fragment carry partial sequences. Annotation rules often require full-length or nearly full-length coverage, so fragment entries frequently lack domains and function even when the missing region is the only problem. Check whether a longer isoform exists for the same gene, and whether the RefSeq or Ensembl record has a longer transcript model than the one that reached UniProt. ### Isoforms [Alternative splicing](/blog/guides/alternative-splicing) produces multiple isoform entries per gene. Annotation often applies to only one isoform, or applies to the canonical sequence with notes about isoform differences. If you annotated the long isoform in your analysis but the curated entry describes a short one, confirm which isoform each source describes before calling it a gap. ### Sequence conflicts and warnings Entries can carry sequence conflict reports, where different sources disagree about residues, or warnings about frameshifts in the underlying genome. A conflict in a catalytic region can cause curators to soften or withhold functional claims. Read the Sequence section carefully before assuming annotation was overlooked. ## Cause six: search and query mechanics Some "gaps" are interface problems, and they are worth learning to rule out because they are cheap to fix. **Field search versus free text.** UniProt supports field-restricted queries such as `gene:`, `organism_name:`, `protein_name:`, `reviewed:`, and `existence:`. Field search is exact or wildcard controlled, while free text is fuzzier. A common mistake is searching a protein description in free text, getting thousands of loose matches or none, and concluding the data is missing. **Case sensitivity and wildcards.** UniProt search is case insensitive for most fields, but gene symbols benefit from exact field syntax. Use `gene:tpi*` style wildcards when unsure of the exact symbol. **Keyword versus GO.** Keywords are a flat controlled vocabulary curated by UniProt, while GO terms come from the Gene Ontology Consortium through multiple mapping routes. A protein can have GO terms and no keywords or the reverse. Neither is a subset of the other. **Version drift in scripts.** REST query syntax, field names, and redirect behavior can change between releases. A script that worked last year can return empty results today. Test your query against a single known accession first, requesting the full `.txt` flat file, and compare against the website before debugging your pipeline logic. ## Cause seven: annotation changed, moved, or disappeared Troubleshooting uniprot annotation gaps sometimes means chasing annotation that used to be there. ### The mechanism UniProt entries carry both a sequence version and an entry version. Curators revise entries, merge duplicate entries, split entries, and retire accessions. Automatic annotation rules are also updated, and occasionally an automatic annotation is withdrawn when the underlying rule is corrected. Between releases, the same accession can legitimately display different annotation. ### How to confirm and fix 1. **Check the version history** listed on the entry, including the dates and version numbers of recent modifications. 2. **Use the archive.** UniProt publishes complete releases for download, so you can retrieve the exact release your previous analysis used. Reproducible pipelines should pin a release version or a snapshot date, the same way they pin tool versions. 3. **Re-derive rather than diff blindly.** If annotation vanished, check whether it moved to a merged entry or was replaced by a more specific term. Curation updates usually replace broad statements with precise ones, which looks like a loss in a naive diff. ## Practical UniProt tutorial: querying, batching, and scripting This section consolidates the mechanics, because most troubleshooting ends in a command. ### Single entry retrieval The REST API serves every entry in multiple formats: ``` curl "https://rest.uniprot.org/uniprotkb/P04637.txt" ``` This returns the full flat file for human p53, including every annotation line and evidence tag. Changing the extension to `.fasta`, `.json`, or `.gff` changes the format. If the browser shows annotation but your API call does not, fetch the `.txt` version first and inspect it, because the flat file is the complete record. ### Batch retrieval with field selection For a list of accessions, request a tab-separated file with the fields you need: ``` curl -H "Accept: text/tab-separated-values" \ "https://rest.uniprot.org/uniprotkb/search?query=reviewed:true+AND+organism_id:9606&fields=accession,id,protein_name,gene_primary,go_id&size=500" ``` The `fields` parameter takes a comma-separated list of field names, and `size` controls page size. Paginate with the link header that the API returns rather than trying to fetch everything in one call. ### ID mapping at scale For converting hundreds of gene names or RefSeq identifiers, use the ID mapping service: submit the identifier list, choose the target database, wait for the job to finish, then fetch results. The web interface covers small jobs, and the REST endpoints at `rest.uniprot.org/idmapping/` handle programmatic use. Mapping results include the mapped UniProt accession plus a score, and unmapped identifiers come back listed so you can see exactly what failed. ### SPARQL for structured questions The UniProt SPARQL endpoint at `sparql.uniprot.org` lets you query UniProtKB with RDF triples, which is the right tool for questions like "give me every reviewed human kinase with a PDB structure and its GO molecular function terms". For most people, the REST API covers daily needs and SPARQL covers the analytical ones. ### Downloads for offline work If your project needs a whole proteome or a full release subset, download the compressed files from the UniProt downloads page rather than paginating through the API. Pin the release number in your methods section. **Data handling note.** Public web services such as BLAST at UniProt and NCBI are not appropriate for unpublished sequences bound by confidentiality agreements, data use restrictions, or pending patents. Run those analyses locally with command-line tools such as HMMER and BLAST+ instead of pasting restricted sequences into public forms. ## Building your own annotation when UniProt has none ![Five steps from domain scanning through orthology transfer, confidence tiers, localization checks and depositing findings.](/article-images/illustrations/uniprot-missing-annotation-troubleshooting-build-annotation.webp) When you have confirmed the gap is real, here is a defensible workflow. 1. **Structural first, functional second.** Run InterProScan on your sequences to get domain architecture. Domains are the most transferable pieces of annotation because they are sequence-based and well-defined. 2. **Orthology over best hit.** Run eggNOG-mapper or an orthology-aware method rather than taking the single best BLAST hit. Best-hit transfer fails on paralogs, and paralog confusion is the most damaging silent error in function transfer. 3. **Confidence tiers.** Write your transferred annotation into three tiers: experimentally characterized direct ortholog, inferred by family membership, and remote homolog hypothesis. Assign each predicted protein a tier and keep the tier label attached to the annotation wherever it travels. 4. **Validate the obvious.** Check predicted transmembrane regions and signal peptides with dedicated predictors, because localization predictions often explain more about function than a weak BLAST hit does. 5. **Deposit what you learn.** Experimental evidence submitted to UniProt becomes part of the permanent record, raising the protein existence level and replacing inference with measurement. ## When not to fill the gap A missing annotation is sometimes the correct state of the record. If a protein has no detectable domains, no significant homologs, and no expression data, the honest annotation is "uncharacterized." Filling the gap with a speculative name, an unjustified GO term, or a copied function from a distant relative propagates errors into databases that harvest your work. UniProt's own evidence framework exists to prevent exactly this, and mirroring its discipline in your own outputs is the single best habit you can build. Over-annotation is harder to undo than under-annotation, because downstream users rarely recheck a confident-looking claim. ## Prevention practices A few habits prevent most of the failures above from recurring. - **Pin release versions.** Record the UniProt release number and download date for every analysis. Archive releases remain available. - **Access by accession, map by tool.** Never hard-code gene symbols into pipelines. Store accessions, and use ID mapping when you must start from names. - **Cache defensively.** If you cache API responses, store the full `.txt` or `.json` record rather than extracted fields, so future field name changes do not break your archive. - **Restrict queries to organism and proteome.** Add `organism_id` and proteome filters to every query as a default, not an afterthought. - **Log evidence, not just results.** Wherever you store annotation, store the evidence tag or your own confidence tier alongside it. - **Re-run the five-minute diagnostic after every release.** A scheduled check of a handful of key accessions catches silent annotation drift before it contaminates a downstream analysis. ## Common Mistakes and Limitations **Treating TrEMBL annotation as curated fact.** Automatic annotations in unreviewed entries are computational inferences. They are often right, but they are not the same class of claim as a curator-backed reviewed entry, and analyses should not treat them identically. **Transferring function from a single distant BLAST hit.** Identity percentage alone, especially below 50 percent, does not establish shared function. Paralogs within one family diverge enormously. Use orthology methods and require multiple lines of evidence before transfer. **Assuming an empty field means missing data everywhere.** Before building your own annotation, confirm the gap exists in the flat file itself, not just in your filtered view. Request the full `.txt` record and read it. **Using gene names as primary keys.** Gene naming conventions change, synonyms proliferate across databases, and one symbol can map to several entries. Accessions and sequences are stable identifiers. Names are not. **Ignoring isoforms and fragments.** Comparing your transcript-derived sequence against the canonical isoform only can make a complete protein look like a fragment, and vice versa. Check which isoform each source describes. **Forgetting that absence of evidence is not evidence of absence.** An entry with no function section means no one has curated evidence for a function in UniProt yet. It does not mean the protein lacks function, and it does not mean no paper describes one, since literature coverage of TrEMBL entries is incomplete. **A limitation of this guide itself.** UniProt changes constantly. Release content, field names, and interface behavior evolve, and specific counts of entries or annotations go out of date quickly. The procedures here are stable, but always verify details against current UniProt documentation before relying on them in published work. Individual proteins also differ enough that no general workflow substitutes for reading the actual entry, the linked literature, and the primary experimental evidence for your specific protein of interest. ## Frequently Asked Questions ### Why does my UniProt entry have no function annotation? Most likely the entry is in TrEMBL, the unreviewed section of UniProtKB, and no automatic annotation rule matched the protein. Check the Reviewed/Unreviewed badge on the entry and the protein existence level, then BLAST against Swiss-Prot and run InterProScan to build annotation yourself. ### What is the difference between Swiss-Prot and TrEMBL? Swiss-Prot entries are manually reviewed by UniProt curators with literature-based annotation. TrEMBL entries are generated automatically from source databases and receive only computational annotation. Swiss-Prot is a small minority of UniProtKB by entry count. ### How do I convert a gene name to a UniProt accession? Use the UniProt ID mapping tool or REST endpoints, which convert identifiers from NCBI Gene, Ensembl, RefSeq, and many other sources to UniProtKB accessions. Search with the `gene:` field operator for quick single-gene lookups. ### Why did annotations change between UniProt releases? Curators revise, merge, and retire entries continuously, and automatic annotation rules are updated as families are redefined. Check the entry version history, and pin specific release versions in your pipelines for reproducibility. ### Can I trust annotations marked "By similarity"? Treat them as reasonable inferences from a characterized homolog rather than direct evidence for your protein. UniProt labels these explicitly so you can weigh them appropriately, and any critical claim should be checked against the literature for the source homolog. ### How do I find annotations for a protein from a non-model organism? Search within the organism's proteome, confirm the proteome is flagged as complete, then use BLAST against Swiss-Prot, InterProScan, and orthology tools such as eggNOG-mapper to build annotation from homologs and domains. ### How do I download annotations in bulk? Use the REST API with `fields` and pagination for moderate batches, the ID mapping service for identifier conversion, and the downloads page for whole proteomes or full release subsets. ### When should I annotate a protein myself instead of waiting for UniProt? When you need the annotation now for a non-model organism, when the entry is unreviewed with no matched rules, or when you have experimental evidence UniProt lacks. Document your evidence chain, assign confidence tiers, and consider submitting experimental findings back to UniProt.