Diagnose and fix BiocManager install and version-mismatch failures

TL;DR

For "Error: .onLoad failed in loadNamespace() for 'BiocManager', details:": install warns the package "is not available", e.g.: Bioconductor version 3.18 (BiocManager 1.30.22), R 4.3.2 Patched (2023-11-07 r85494) Installing package(s) 'Rcollectl' Warning message: package 'Rcollectl' is not available ( for R version 4.3.2 Patched) C. Install silently finds nothing: the output says 'getOption("repos")' replaces Bioconductor standard repositories and lists only a CRAN mirror.

Error: .onLoad failed in loadNamespace() for 'BiocManager', details:
  call: NULL
  error: Bioconductor version '3.8' requires R version '3.5'; see
  https://bioconductor.org/install

When to use

You are seeing this: Bioconductor repositories were never consulted. Use this skill when you run into "Diagnose and fix BiocManager install and version-mismatch failures".

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.

Use this when BiocManager::install() fails or warns, library(BiocManager) refuses to load, BiocManager::valid() reports an invalid installation, or a package that should exist "is not available". Almost every BiocManager failure is one of five distinct problems with different fixes, and this procedure tells them apart before you reinstall anything.

1. Read the symptom and classify first

A. .onLoad failed in loadNamespace() for 'BiocManager', the loader prints something like:

Error: .onLoad failed in loadNamespace() for 'BiocManager', details:
  call: NULL
  error: Bioconductor version '3.8' requires R version '3.5'; see
  https://bioconductor.org/install

B. Install warns the package "is not available", e.g.:

Bioconductor version 3.18 (BiocManager 1.30.22), R 4.3.2 Patched (2023-11-07 r85494)
Installing package(s) 'Rcollectl'
Warning message:
package 'Rcollectl' is not available ( for R version 4.3.2 Patched)

C. Install silently finds nothing: the output says 'getOption("repos")' replaces Bioconductor standard repositories and lists only a CRAN mirror. Bioconductor repositories were never consulted.

D. BiocManager::valid() reports out-of-date or too-new packages, a library containing packages from more than one Bioconductor release.

E. Large package downloads stall mid-way: e.g. org.Hs.eg.db (~80 MB) with downloaded 15.1 MB and no completion.

Classify before acting; each maps to a different fix below.

2. Diagnose A: stale BiocVersion after an R upgrade

The mechanism, documented in the BiocManager vignette: BiocManager uses the BiocVersion package to record which Bioconductor release the library belongs to. After upgrading R (e.g. 3.5.x to 3.6.x, or 4.4 to 4.5), the recorded Bioconductor version is no longer valid for the new R, and the .onLoad check refuses to load. Check the pairing:

R.version.string          # what R is running
BiocManager::version()    # what Bioconductor this library targets

Each Bioconductor release is designed for a specific R version: Bioconductor 3.22 requires R 4.5, 3.18 pairs with R 4.3, and so on. packageVersion("BiocVersion") follows the Bioconductor release (e.g. BiocVersion 3.22.0 depends on R >= 4.5.0).

Fix options, in order of preference:

1. Preferred: use a separate library per R/Bioconductor version. Install only base R into the system location and keep one library directory per R/Bioc pairing. This preserves reproducibility of old analyses; the alternative below destroys it.

2. Otherwise, rebuild the existing library in place. Remove every copy of the stale marker, then update everything:

remove.packages("BiocVersion")  # repeat until all instances are gone
BiocManager::install()          # installs current BiocVersion, updates all packages
BiocManager::valid()            # confirm the installation is valid for this R

Answer "yes" when asked to update a large number of packages. The trade-off the vignette is explicit about: the previous Bioconductor version is removed, so results produced under the old release can no longer be reproduced from this library.

3. Diagnose B: "package not available"

Work through these, in order:

1. Release vs devel branch. Bioconductor has a 'release' branch (current R) and a 'devel' branch where new packages land first, then roll into release at the next April/October release. If the package is devel-only, you must opt in:

BiocManager::install(version = "devel")
BiocManager::install("the-package")

2. Platform support. A few packages are not available on every OS because they need software the OS lacks. Check the package's build report page for which platforms have passing builds.

3. Spelling. Check the exact capitalization and spelling of the package name against the package landing page. Bioconductor installers do not fuzzy-match.

4. Diagnose C: your repos option shadows Bioconductor

If install.packages() or an earlier options(repos = ...) call replaced the repository list, Bioconductor repos are never queried. BiocManager::install() handles repositories itself, do not set a bare CRAN repos option first and expect it to reach Bioconductor. For installing local or GitHub packages against the right repositories, pass Bioconductor's repository list explicitly:

remotes::install_local("./org.Vdahliae.eg.db",
                       dependencies = TRUE,
                       repos = BiocManager::repositories())

Note also that BiocManager does not install local package files at all; local tarballs go through install.packages(..., repos = NULL, type = "source") or remotes::install_local.

5. Diagnose D: mixed-release library

BiocManager::valid() is the ground truth for library coherence. If it reports packages that are out of date or too new for the current release, bring the whole library to the current release with no arguments:

BiocManager::install()   # updates all out-of-date Bioconductor packages
BiocManager::valid()     # re-check until it reports valid

The Installation paths not writeable warning on Windows is a folder-permission artifact; it can be ignored as long as .libPaths()[1] points at a writeable library.

6. Diagnose E: download timeouts on large packages

BiocManager sets options(timeout = 300) (5 minutes), which is too short for large annotation packages on slow connections, the classic case is org.Hs.eg.db at ~80 MB downloading only a fraction before stalling. Raise the timeout for the session before installing:

options(timeout = 1200)              # 20 minutes, for the slow-download case
BiocManager::install("org.Hs.eg.db")

7. Checklist for the failing install

1. Classify: A (.onLoad / version requires), B (not available), C (repos replaced), D (valid() mixed), E (timeout).

2. A: check BiocManager::version() against the R version; prefer a version-specific library; otherwise remove all BiocVersion copies, BiocManager::install(), BiocManager::valid().

3. B: devel vs release, then platform build reports, then spelling.

4. C: never shadow Bioconductor repos; use BiocManager::repositories() for remotes installs.

5. D: BiocManager::install() with no arguments, then BiocManager::valid().
6. E: options(timeout = ...) before installing large annotation packages.

Variants

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

options(timeout = 1200) # 20 minutes, for the slow-download case

options(timeout = 1200)              # 20 minutes, for the slow-download case
BiocManager::install("org.Hs.eg.db")

Grounded in the BiocManager vignette 'Cannot load BiocManager' section (verbatim .onLoad error text, BiocVersion mechanism, remove.packages('BiocVersion') remediation, separate-library-per-R-version recommendation, BiocManager::valid() confirmation, options(timeout=300) behavior and the 79.4 MB org.Hs.eg.db timeout example) and the Bioconductor FAQ 'BiocManager::install() warns that a package is not available' section (release vs devel branches, April/October releases, platform availability and build reports, spelling/capitalization). Release pairings: Bioconductor 3.22 release announcement (Oct 30, 2025, requires R 4.5) and BiocVersion 3.22.0 Depends R >= 4.5.0; the R 4.3.2 / BiocManager 1.30.22 / Bioc 3.18 triplet from a support thread, including the 'getOption(repos) replaces Bioconductor standard repositories' message and the BiocManager::repositories() remedy for local installs.