# Fix Galaxy tool dependency resolution failures
Use this when a Galaxy tool fails because its software dependencies cannot be
found or installed, when Admin shows "Missing repository/tool dependencies" for
an installed tool, when a job dies before the tool ever runs, or when the tool
binary fails with missing libraries. Most of these look like "the tool is
broken" but are one of four distinct resolution-chain problems with different
fixes — classify FIRST from observable evidence, then touch configuration.
## 1. How Galaxy resolves a tool's requirements
A tool's XML declares requirements like
`<requirement type="package" version="1.3.1">samtools</requirement>`. Galaxy
passes them through **dependency resolvers** in order and uses the **first
success** — later resolvers are never tried. The default chain, configured via
`dependency_resolvers` in `galaxy.yml`, is:
1. `tool_shed_packages` — legacy packages from `tool_dependencies.xml`
(deprecated; only relevant for old Tool Shed tools)
2. `galaxy_packages` — admin-curated dirs under `tool_dependency_dir`
3. `conda` — versioned match
4. `galaxy_packages` with `versionless: true`
5. `conda` with `versionless: true`
The conda resolver builds one environment per tool: a single requirement
becomes `[conda_prefix]/envs/__samtools@1.3.1`; multiple requirements become
`mulled-v1-[hash]` (hash derived from the requirement names and versions).
Three defaults surprise everyone:
- `conda_auto_install` defaults to **false** — Galaxy will *not* install
missing dependencies before a job runs unless you enable it.
- `conda_auto_init` defaults to **true** — Galaxy bootstraps its own conda
from the web if none is found.
- `conda_ensure_channels` defaults to `iuc,conda-forge,bioconda,defaults`,
the Bioconda prescribed channel order. Changing the order changes which
build of a package you get.
(The old `dependency_resolvers_conf.xml` file still works but is deprecated;
its docs only exist in Galaxy releases prior to 21.09.)
## 2. Classify from observable evidence
### A. Admin shows "Missing repository/tool dependencies"
The tool came from the Tool Shed with legacy `tool_dependencies.xml`
packages that were never installed. Per IUC best practice, all new/updated
Tool Shed tools must resolve via conda, so this resolver is legacy-only.
- Fix: Admin → manage the tool's dependencies and install them, or reinstall
a current IUC-maintained version of the tool that uses conda requirements.
- Do not hand-edit the tool XML to delete requirements (the mailing-list
"arduous" path of vendoring system packages and editing XML is a last
resort, not a first step).
### B. Job fails immediately and no conda env exists for the tool
Look under `[conda_prefix]/envs/` (default
`[tool_dependency_dir]/_conda/envs/`): no `__[name]@[version]` and no
`mulled-v1-*` for the tool means **no resolver produced an environment**.
- Check `conda_auto_install` — with the default `false`, Galaxy never creates
the env and the job fails at setup. Set `conda_auto_install: true` in
`galaxy.yml` (globally) or `auto_install: true` on the conda resolver.
- Check the resolver chain in `galaxy.yml`: a misconfigured early resolver
can shadow conda. Turn on `conda_debug: true` and read the Galaxy log for
the exact conda commands attempted.
- Check channels: `conda_ensure_channels` must keep the Bioconda order
(`iuc,conda-forge,bioconda,defaults`) if it includes bioconda.
### C. The env exists but the tool binary fails at runtime
Signatures: `command not found` for a tool that "installed fine",
`No module named X`, `symbol lookup error: .../libreadline.so.6: undefined
symbol`, or the classic:
```
DependencyException: Conda dependency seemingly installed but failed to build job environment.
```
The environment was created but is broken — this is an environment problem,
not a resolver problem. Do not reorder resolvers; rebuild the env:
1. Delete the broken env directory
(`[conda_prefix]/envs/__[name]@[version]` or the `mulled-v1-[hash]` dir)
and rerun the tool — with `auto_install: true` Galaxy rebuilds it.
2. If the failure names a specific library (historically `libbz2.so.1.0`,
`libreadline.so.6`), activate the env manually and reinstall that package
from the top-priority channel (`iuc`, then `conda-forge`).
3. `PaddingError: Placeholder of length '80' too short in package ...
The package must be rebuilt with conda-build > 2.0` means the install
prefix path was too long for the package's binary placeholders — keep
`conda_prefix` short and retry.
### D. The wrong version of a dependency is picked up
Because resolution is first-success-wins, an older `tool_shed_packages` or
`galaxy_packages` entry that happens to match the name shadows the conda
package you actually want. Inspect which resolver matched (the Admin
dependency view shows how each requirement resolves), then reorder
`dependency_resolvers` in `galaxy.yml` — e.g. conda before
`galaxy_packages` — or remove the stale manual entry.
## 3. The configuration to check
In `galaxy.yml`, global keys that matter:
- `conda_prefix` (default `[tool_dependency_dir]/_conda`)
- `conda_exec` (defaults to conda on `$PATH`, else `[conda_prefix]/bin/conda`)
- `conda_debug` — log the conda commands; turn on while diagnosing
- `conda_ensure_channels` — keep `iuc,conda-forge,bioconda,defaults` order
- `conda_auto_install` — must be `true` for on-demand installs (default false)
- `conda_auto_init` — bootstrap conda from the web (default true)
- `tool_dependency_dir` — base for `galaxy_packages` lookups
Per-resolver keys (inside `dependency_resolvers`): `type`, `versionless`,
`prefix`, `exec`, `debug`, `ensure_channels`, `auto_install`, `auto_init`,
`copy_dependencies`, `read_only`. A common production pattern is two conda
resolvers — a read-only curated install first, Galaxy-managed second:
```yaml
galaxy:
dependency_resolvers:
- type: conda
auto_init: false
auto_install: false
read_only: true
prefix: /hpc/conda
- type: conda
auto_init: true
auto_install: true
prefix: /galaxy/conda
```
## 4. Checklist
1. Classify: A (Admin shows missing Tool Shed deps), B (no env created),
C (env exists but broken), or D (wrong version resolved).
2. A → install via Admin or move to a conda-based tool version.
3. B → enable `conda_auto_install`, verify channels and resolver order,
use `conda_debug` to see the failing command.
4. C → delete the env dir and let Galaxy rebuild; fix channel mix or
prefix length if it recurs.
5. D → reorder `dependency_resolvers` so the intended resolver wins.
6. Tool developers: verify with `planemo test` before blaming the server —
a `<requirement>` naming a package that does not exist on conda fails
at class B on every server.