# Fix conda / Bioconda install conflicts and solver failures

Diagnose conda/Bioconda install failures: classify genuine version conflicts (UnsatisfiableError) vs slow classic solver vs wrong channel order vs unresolvable YAML from the exact error text, then apply the matching fix (fresh env and unpinning, libmamba solver, conda-forge-first strict channel priority).

Exact reference: {"kind":"skill_version","skill_id":"skl_6zM7ceqfjX_IwFJGWqHLeQ","version_id":"skv_92V93bhN4G8hMGT32ACO6w"}

Applicability: [{"constraint":">=4.10 (channel_priority strict and --solver/libmamba-solver support)","technology":"conda","version_scheme":"semver"},{"constraint":"current channel recipes; Python 3.10-3.13 builds per Bioconda docs","technology":"bioconda","version_scheme":"unknown"}]

# Fix conda / Bioconda install conflicts and solver failures

Use this when `conda install` or `conda create` with Bioconda packages fails
with `UnsatisfiableError`, hangs on `Solving environment`, or reports
`Found conflicts!`. These errors look alike but have four distinct causes with
different fixes. Classify from the exact error text FIRST — the fix for a
genuine version conflict is the opposite of the fix for a slow solver.

## 0. Read the error text, not just "it failed"

The three signatures:

```
UnsatisfiableError: The following specifications were found to be incompatible with each other:
```
→ a genuine version conflict (class A).

```
Solving environment: failed with initial frozen solve. Retrying with flexible solve.
...
Found conflicts! Looking for incompatible packages.
This can take several minutes.  Press CTRL-C to abort.
```
hanging for a long time → the classic solver is struggling (class B), or a
real conflict it will eventually report (class A).

```
Your installed version is: 2.35
```
attached to a `__glibc` complaint → the system glibc is too old for the
requested builds (class A, system-level).

## 1. Class A — genuine version conflict (`UnsatisfiableError`)

The solver is telling the truth: the requested combination cannot exist.
Common triggers seen on Biostars:

- **Installing into an existing environment** (especially `base`). The
  existing packages pin half the dependency tree. Almost every "conda error"
  thread is fixed the same way — install into a **fresh environment**:

  ```bash
  conda create -n sratools -c conda-forge -c bioconda sra-tools
  conda activate sratools
  ```

- **Over-pinned versions.** `samtools=1.9` on a new conda-forge stack fails
  because the old recipe's `libgcc-ng`/`libstdcxx-ng`/`zlib` pins collide with
  what modern python pulls in. Unless you have a hard reason for the old
  version, drop the pin and let the solver pick; then pin the *resolved*
  versions (`conda list --export`) for reproducibility.

- **Python version drift.** Bioconda currently builds for Python 3.10–3.13;
  old recipes expecting older Pythons conflict with the current stack.
  If you must have an old package, create the env with an old python
  explicitly (`conda create -n old -c conda-forge -c bioconda python=3.9
  [pkg]`) instead of fighting the default.

- **System glibc too old.** Errors naming `__glibc` (e.g. recipe needs
  `>=2.17` and the system reports something older) cannot be solved by
  channel juggling — you need a newer OS image or a container.

Do not "fix" class A by adding more channels or `--force`; that hides the
conflict until runtime.

## 2. Class B — solver hangs or crawls (no `UnsatisfiableError` yet)

The classic conda solver is slow on Bioconda's large dependency graph. Check
the solver first:

```bash
conda --version
```

- **conda 23.10 or newer**: the libmamba solver is already the default. If
  solving still hangs, it's probably a genuine conflict (class A) — let it
  finish or Ctrl-C and read the report.
- **conda older than 23.10**: install the faster solver and make it default:

  ```bash
  conda update -n base conda
  conda install -n base conda-libmamba-solver
  conda config --set solver libmamba
  ```

  or use it for one command only:

  ```bash
  conda install -c conda-forge -c bioconda [pkg] --solver=libmamba
  ```

- **Alternative**: `mamba` / `micromamba` are drop-in replacements that use
  the same libsolv-based solver and the same channels:

  ```bash
  mamba create -n tools -c conda-forge -c bioconda samtools bcftools
  ```

## 3. Class C — wrong channel order / priority

Bioconda's documented setup (bioconda.github.io) — order matters because
`conda config --add` **prepends**, so add in this exact sequence to end up
with conda-forge at highest priority:

```bash
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict
```

Resulting priority (highest first): `conda-forge`, `bioconda`. Rationale from
the docs: Bioconda heavily depends on conda-forge, so conda-forge must win for
general-purpose libraries; `strict` priority "avoids cryptic errors" by
respecting that order during solving instead of mixing channels per package.

Diagnose: `conda config --show channels` — if `bioconda` outranks
`conda-forge`, or `channel_priority` is `flexible`/`disabled`, fix it with
the three commands above.

Without touching `.condarc`, pass the same policy per command (note: on the
command line, `-c` flags are read in *decreasing* priority order, the reverse
of `conda config`):

```bash
conda create -n myenv -c conda-forge -c bioconda --strict-channel-priority samtools bwa
```

## 4. Class D — environment YAML won't resolve

For `conda env create -f env.yml` conflicts:

1. Check the `channels:` list in the YAML — it must list `conda-forge`
   before `bioconda` (same priority rule as class C).
2. Loosen or drop version pins on the *tools* (`samtools`, `rsubread`);
   over-pinning transitive deps (`libgcc-ng=...`) is the usual culprit —
   remove them first, re-add only what still resolves.
3. Solve with mamba (`mamba env create -f env.yml`); its error messages name
   the conflicting chain more precisely than conda's.

## Quick decision tree

1. `UnsatisfiableError` → fresh env, drop pins, check python/glibc (class A).
2. Hangs at `Solving environment` / `Found conflicts!` → conda ≥23.10?
   yes: wait for the real report; no: libmamba solver (class B).
3. Worked before, fails now on a new machine → `conda config --show channels`;
   fix order to conda-forge > bioconda + strict priority (class C).
4. YAML create fails → channel order in YAML, unpin tools, solve with mamba (class D).
5. Never install bioinformatics tools into `base`; never "fix" a conflict with `--force`.


## Supporting basis and limitations

Built from Bioconda's official setup docs (channel order conda-forge above bioconda via sequential conda config --add, channel_priority strict) and the conda-libmamba-solver user guide (libmamba default from conda 23.10; --solver=libmamba for older conda), grounded in recurring Biostars threads on UnsatisfiableError, Solving-environment hangs, and YAML conflicts.

## Change and rationale

New skill: fix conda / Bioconda install conflicts and solver failures.

Bioconda install failures are among the most-asked Biostars questions and the three failure modes demand opposite fixes: a genuine conflict needs unpinning and a fresh env, while a hanging solver needs libmamba, and neither is fixed by the other's remedy. This skill adds a classify-first decision procedure plus Bioconda's documented channel-order setup so agents stop guessing.