Diagnose Bioconductor annotation failures: org.db ID mapping and TxDb genome-build mismatches

TL;DR

Step 2, if there is no error but most results are NA: check the data vintage. org.db packages are rebuilt from the current NCBI/Ensembl snapshot at each Bioconductor release, and the package version tracks the release (e.g. org.Hs.eg.db_3.12.0 shipped with Bioconductor 3.12). The org.db interface is AnnotationDbi: select(), mapIds(), keytypes(), columns(), keys().

packageVersion("org.Hs.eg.db")   # which snapshot you are mapping against
sum(is.na(symbols))              # how many keys failed to map

When to use

You are seeing this: Annotation failures split into identifier-mapping failures and genome-build failures; classify which you have before remapping anything. Use this skill when you run into "Diagnose Bioconductor annotation failures: org.db ID mapping and TxDb genome-build mismatches".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Use this when select() / mapIds() on an org.*.db package returns all NAs, throws keytype errors, or gives 1:many mappings you did not expect, or when coordinates from a TxDb package disagree with your data (silently empty overlaps, gene positions that look wrong). Annotation failures split into identifier-mapping failures and genome-build failures; classify which you have before remapping anything.

1. Failure class A: org.db ID mapping errors and NA floods

The org.db interface is AnnotationDbi: select(), mapIds(), keytypes(), columns(), keys(). The package name encodes the organism and the key type org.Hs.eg.db means human, Entrez Gene central keys ('eg' = Entrez Gene).

Step 1, read the exact error.

unable to find an inherited method for function 'mapIds' for signature '"character"' means the first argument was a character string, not the database object. A frequent cause: storing the package name in a variable.

library(AnnotationDbi)
library(org.Hs.eg.db)

# WRONG: org_pkg is a string; mapIds has no method for character
org_pkg <- "org.Hs.eg.db"
mapIds(org_pkg, ids, "ENTREZID", "ENSEMBL")

# RIGHT: pass the loaded database object
org_pkg <- org.Hs.eg.db
mapIds(org_pkg, ids, "ENTREZID", "ENSEMBL")

None of the keys entered are valid keys for 'X'. Please use the keys method to see a listing of valid arguments. means the keytype does not match the identifier flavor you passed. Discover what the package actually offers:

keytypes(org.Hs.eg.db)   # identifier flavors accepted as keytype
columns(org.Hs.eg.db)    # columns you may request
head(keys(org.Hs.eg.db, keytype = "ENSEMBL"))  # what keys look like

Typical mistake: passing Ensembl IDs (ENSG...) with keytype = "ENTREZID" or gene symbols with keytype = "ENSEMBL".

Step 2, if there is no error but most results are NA: check the data vintage. org.db packages are rebuilt from the current NCBI/Ensembl snapshot at each Bioconductor release, and the package version tracks the release (e.g. org.Hs.eg.db_3.12.0 shipped with Bioconductor 3.12). IDs retired or renamed since your IDs were generated, versioned Ensembl IDs with the .11 suffix that changed, withdrawn symbols, merged Entrez records, return NA because they no longer exist in the snapshot:

packageVersion("org.Hs.eg.db")   # which snapshot you are mapping against
sum(is.na(symbols))              # how many keys failed to map

Fixes: strip Ensembl version suffixes (sub("[.].*$", "", ids)) if the snapshot predates them, match the org.db vintage to the vintage that produced the IDs, and accept that a small NA fraction is normal (withdrawn records), not a bug in your code.

Step 3, duplicate mappings are expected; choose the resolution. Gene identifiers are often 1:many. select() returns all rows; mapIds() requires keytype and takes a single column, resolving duplicates via multiVals (default "first"). Alternatives: "list", "CharacterList", "filter", "asNA", or a user-supplied function:

mapIds(org.Hs.eg.db, ids, "SYMBOL", "ENSEMBL", multiVals = "list")

If a script "worked" on an old org.db and now returns different symbols, the vintage changed, not the code, pin the package version.

2. Failure class B: TxDb genome-build and chromosome-name skew

TxDb package names encode the source and the genome build, e.g. TxDb.Hsapiens.UCSC.hg19.knownGene (UCSC, hg19, knownGene track). The current-build counterpart follows the same scheme with hg38. Two independent things must agree with your data the build and the chromosome naming.

Step 1, confirm the build. The coordinates in a TxDb are only valid for its build:

library(TxDb.Hsapiens.UCSC.hg38.knownGene)
txdb <- TxDb.Hsapiens.UCSC.hg38.knownGene
genome(txdb)     # e.g. "hg38" -- must match the reference your reads were aligned to

If the alignments used hg38 and the TxDb is hg19, overlaps and gene coordinates are silently wrong, nothing errors, the numbers just disagree. There is no automatic fix; install the TxDb for the build that matches the data.

Step 2, confirm the chromosome-name style. findOverlaps() matches the triplet (seqname, range, strand), so chr1 in your data vs 1 in the TxDb yields zero hits with no warning. Check and convert with GenomeInfoDb:

library(GenomeInfoDb)
seqlevelsStyle(txdb)          # e.g. "UCSC" (chr1) vs "NCBI" (1)
seqlevelsStyle(txdb) [- "NCBI"  # renames chr1 -] 1, chrM -> MT, etc.

Do the conversion on one side so both sides share a style, then re-run the overlap. To drop unplaced scaffolds and alt contigs before comparing:

txdb <- keepStandardChromosomes(txdb, pruning.mode = "coarse")

Step 3, sanity-check the overlap result, not just the code. After alignment of build and style, spot-check with countOverlaps() or subsetByOverlaps() on a known gene (e.g. pull transcripts(txdb) for a housekeeping gene and confirm your reads overlap it). Zero overlaps after the build/style check points back to the counting stage, not the annotation.

3. Failure class C: AnnotationHub / ExperimentHub cache errors

Packages that fetch hub resources at load time can fail with:

error: Invalid Cache: sqlite file
Hub has not been added to cache
Run again with 'localHub=FALSE'

The local hub cache was never initialized or is corrupt. Initialize it first, answering "yes" if prompted to create the local cache directory, then re-install or re-load the package:

AnnotationHub::AnnotationHub()      # or ExperimentHub::ExperimentHub()

The AnnotationHub vignette "Troubleshooting the Cache" documents the recovery steps for the persistent cases.

4. Checklist for the failing annotation step

1. Classify: A (ID mapping: error or NA flood), B (TxDb coordinates: silent

wrong/empty results), C (hub cache error at load).

1. A-error: pass the db object, not the package-name string, to mapIds;

discover valid flavors with keytypes()/columns()/keys().

1. A-NA: compare packageVersion("org.Hs.eg.db") against the vintage that

produced the IDs; strip version suffixes; resolve 1:many with multiVals.

1. B: genome(txdb) must equal the alignment build; seqlevelsStyle() must

match on both sides, convert one side, then re-run overlaps; keepStandardChromosomes(..., pruning.mode = "coarse") to drop alt contigs.

1. C: initialize the hub with AnnotationHub() / ExperimentHub() before

installing or loading.

Variants

Other phrasings of the same problem that show up in reports:

error: Invalid Cache: sqlite file

error: Invalid Cache: sqlite file
Hub has not been added to cache
Run again with 'localHub=FALSE'