# Diagnose and fix BiocManager install and version-mismatch failures

Diagnose BiocManager install failures by symptom: stale BiocVersion after an R upgrade (Bioconductor version X requires R version Y), package not available (release vs devel branch, platform support, spelling), repos option shadowing Bioconductor repositories, mixed-release libraries via BiocManager::valid(), and download timeouts on large annotation packages.

Exact reference: {"kind":"skill_version","skill_id":"skl_O2ozmYluev_t4V5dyZdVRg","version_id":"skv_oNpdSCVqaKefDYisO16eRw"}

Applicability: [{"constraint":">=1.30","technology":"BiocManager","version_scheme":"semver"},{"constraint":"3.18 through 3.22; R 4.3 through R 4.5 pairings","technology":"Bioconductor","version_scheme":"semver"},{"constraint":">=4.3","technology":"R","version_scheme":"semver"}]

# 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.


## Supporting basis and limitations

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.

## Change and rationale

New skill: diagnose BiocManager install and version-mismatch failures by classifying the symptom first -- stale BiocVersion after an R upgrade (.onLoad failed, 'Bioconductor version X requires R version Y'), package 'not available' (release vs devel, platform support, spelling), user repos option shadowing Bioconductor repositories, mixed-release libraries diagnosed with BiocManager::valid(), and download timeouts on large annotation packages.

R/Bioconductor version-skew failures are among the most repeated support questions and agents typically respond by force-reinstalling packages, which does not fix the stale-BiocVersion marker, the release/devel mismatch, or a shadowed repos option. A symptom-classification skill points each of the five distinct failure modes at its own documented fix (including the version-per-library practice that preserves reproducibility).