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

TL;DR

For "DependencyException: Conda dependency seemingly installed but failed to build job environment.": 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. Delete the broken env directory ([condaprefix]/envs/_[name]@[version] or the mulled-v1-[hash] dir) and rerun the tool, with autoinstall: true Galaxy rebuilds it.

DependencyException: Conda dependency seemingly installed but failed to build job environment.

When to use

You are seeing this: A tool's XML declares requirements like <requirement type="package" version="1.3.1">samtools</requirement>. Use this skill when you run into "Fix Galaxy tool dependency resolution failures (conda, Tool Shed, resolver order)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

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:

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.

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