# Diagnose and fix BiocManager install and version-mismatch failures
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
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:
```r
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:
```r
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:
```r
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:
```r
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:
```r
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.