# Fix Galaxy tool dependency resolution failures (conda, Tool Shed, resolver order)

Diagnose why a Galaxy tool's software dependencies fail to resolve or install: classify from the Admin dependency status, missing conda envs (__name@version / mulled-v1-[hash]), and broken-env signatures (DependencyException, PaddingError, symbol lookup errors), then fix via galaxy.yml dependency_resolvers ordering, conda_auto_install, conda_ensure_channels, and targeted env rebuilds.

Exact reference: {"kind":"skill_version","skill_id":"skl_FWuYHNIGBWehA_F1DgFiKg","version_id":"skv_PiqeKhoPWzOPbTT8YpQlFA"}

Applicability: [{"constraint":">=21.09","technology":"Galaxy","version_scheme":"semver"}]

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


## Supporting basis and limitations

Built from the Galaxy Project admin documentation on Dependency Resolvers (default resolver order and first-success-wins semantics, conda resolver parameters, mulled vs __name@version env naming, Bioconda channel order) and recurring failure signatures from the Galaxy mailing lists and help forum (DependencyException 'failed to build job environment', PaddingError placeholder-length errors, 'Missing repository/tool dependencies' in Admin).

## Change and rationale

New skill: diagnose and fix Galaxy tool dependency resolution failures across the resolver chain (tool_shed_packages, galaxy_packages, conda) and conda environments.

Tool dependency failures are the top admin-side Galaxy support topic, and most debugging skips the classification step: admins reorder resolvers when the env is simply broken, or rebuild envs when nothing was ever resolved because conda_auto_install defaults to false. This skill adds a decision procedure that classifies from observable evidence (Admin status, env dir presence, exact error text) before prescribing the fix.