Pin Galaxy tool versions and fix dataset-vs-collection input mismatches in workflows

TL;DR

Use this skill when: a Galaxy workflow stops working after a tool update; a workflow run fails or silently does nothing because a step got a single dataset where it expected a collection (or the reverse); you need to make a workflow reproducible across Galaxy servers or over time; or you are editing a.ga workflow file directly. Check and set it explicitly for every step. Select Upgrade workflow to move every step to its newest installed version.

When to use

You are seeing this: The two concrete failure modes: 1. Use this skill when you run into "Pin Galaxy tool versions and fix dataset-vs-collection input mismatches in workflows".

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.

Galaxy Workflows That Break When Tools Update: Pin Tool Versions and Fix Dataset-vs-Collection Input Mismatches

Use this skill when: a Galaxy workflow stops working after a tool update; a workflow run fails or silently does nothing because a step got a single dataset where it expected a collection (or the reverse); you need to make a workflow reproducible across Galaxy servers or over time; or you are editing a .ga workflow file directly.

The core problem

Galaxy servers install multiple versions of the same tool and show the latest one by default. Tool updates routinely change parameter names, parameter types (a text value becoming an integer is a documented real case), defaults, outputs, and accepted input kinds. A workflow that recorded "whatever version was current" silently shifts behavior the next time the server admin installs an update, runs break, produce different outputs, or stall with empty histories.

The two concrete failure modes:

1. Unpinned tool versions. The workflow does not record which tool version each step ran, so updating the server changes what the workflow does.
2. Dataset vs collection input mismatches. A workflow input defined as an individual dataset is fed a collection at runtime (or the reverse), or a collection of the wrong structure (list vs paired vs list:paired) is connected to a step. The run then fails, or, worse, the invocation page loads but no steps ever schedule.

Pin tool versions in the workflow editor

Every workflow step stores its own tool_version. Check and set it explicitly for every step.

Switch one step's tool version

1. Click Workflows in the Galaxy activity bar (top bar on older servers), find your workflow, and click Edit.
2. Click the tool's node on the canvas.
3. Click the tool-version button for that step. A dropdown lists installed versions as items like Switch to 0.2 or Switch to 0.1+galaxy6.
4. Pick the version your analysis was validated against, then click the Save icon (next to the workflow title) or Save + Exit.

Upgrade all steps at once

1. In the workflow editor, open Workflow Options (the gear/wheel icon, top right).
2. Select Upgrade workflow to move every step to its newest installed version.
3. Review and fix any step that breaks, upgrades change parameters, then Save.

Do this on a copy first. Upgrading is the deliberate moment to re-validate; never let "newest installed" be the default state of a shared workflow.

Reopen old workflows carefully

Opening a workflow whose recorded tool version is no longer installed can show a modal like Using version '0.2' instead of version '0.0.1'. Continuing silently re-points the step at a different tool version. Note which steps changed and re-validate them.

Check the version in the tool form

Open any tool in the Analyze view: the version selector sits behind the versions logo at the top right of the tool form (e.g. a form header reading Galaxy version 0.7.17.1). If the version you need is missing there, it is missing for the workflow too, the server admin has not installed it.

Route dataset collections through the workflow correctly

Choose the right input type

In the workflow editor, expand the Inputs section of the tool panel:

• Input dataset, one single dataset per run.
• Input dataset collection, a collection per run. There are three collection input flavors; after adding one, click its type field and pick the structure that matches your data and the downstream tool's input settings: list, paired, or list:paired.

Getting this right at build time is what lets a collection flow through every step: collections keep their element identifiers across steps, and a tool fed a collection runs once per element and returns a collection of outputs.

Build the collection to match

In the history: click Select Items at the top of the history panel, check the datasets, click n of N selected, and choose Build List or Advanced Build List. In the collection builder wizard pick Flat List, tidy the element names, enter a name, and click Build. For paired-end data, pair by the _1 / _2 filename pattern and confirm the resulting structure (e.g. a paired collection shows sample layer first, forward/reverse layer second).

Supply inputs at runtime the only way that works

A workflow run form cannot take "multiple datasets" or "a collection" for a step that was built with an individual-dataset input. Collections must be explicitly declared as collection Inputs in the editor; only then does the run form offer your history collections for that input. If the run form will not accept your collection, the fix is in the editor, not the form: replace the input with Input dataset collection, set its type, reconnect the noodles, and save.

Fix input dataset vs collection type mismatches

Symptoms: the invocation page shows step scheduling that never starts, an empty history after "successful" submission, or a tool erroring on an input it previously accepted.

Reset the connections after any input change

Changing a workflow input, dataset to collection, collection to dataset, or one collection type to another, invalidates the step metadata downstream. The repair:

1. Open the workflow in the editor.
2. Delete the old input node (or change the input type on the existing one).
3. Disconnect all noodles between the steps and reconnect them from the first step to the last (left to right, in execution order). This resets the internal metadata that otherwise keeps the old input kind.
4. Save and rerun.

Match collection structure to the tool's expectation

• A paired collection (list:paired) into a tool set for single-end input will fail: switch the tool's input selector (e.g. BWA-MEM's Single or Paired-end reads: Paired Collection) or rebuild the collection.
• A tool that takes forward and reverse as one paired input emits a plain list collection (one output per pair), not a paired collection, downstream steps must expect a list.
• Use the Collapse Collection tool to reduce a collection to a single dataset when the downstream step genuinely needs one dataset, not a collection.

Workflow-file and API notes

Exported workflows (.ga JSON) pin versions per step:

• Each step carries tool_id and tool_version, e.g. tool_id: toolshed.g2.bx.psu.edu/repos/bgruening/text_processing/tp_tac/1.1.0 with tool_version: 1.1.0. Treat tool_version as mandatory review in diffs and pull requests.
• When you download a workflow and read steps["0"]["tool_version"], that string is the version that will run. If it names a version the target server lacks, the server substitutes, that is the silent-break mechanism.
• Shared community workflows worth emulating (Intergalactic Workflow Commission style) pin every step and declare collection inputs with explicit types; copy that pattern.

Reproducibility checklist

• [ ] Every step shows an explicit, installed tool version in the editor, none are "latest by default".
• [ ] Inputs are declared: one Input dataset per single dataset, one Input dataset collection with the correct type per collection.
• [ ] After any input or tool-version change, noodles were disconnected and reconnected start to finish, then the workflow was saved.
• [ ] The workflow was run end-to-end after the pin (not just the changed step).
• [ ] The exported .ga diff shows the intended tool_version strings and nothing else moved.

Galaxy shows the latest installed tool version by default and tool updates change parameters/outputs, which is why unpinned steps break (GTN FAQ: 'Tools are frequently updated to new versions. Your Galaxy may have multiple versions of the same tool available'). Per-step version switching uses the tool-version button with 'Switch to X.Y' dropdown items, verified in Galaxy's selenium test suite (testeditortoolupgrade in docs.galaxyproject.org), which also verifies steps store toolversion and that opening an old workflow shows a 'Using version 0.2 instead of version 0.0.1' modal. Bulk upgrade is Workflow Options -> 'Upgrade workflow' per the GTN contributor tutorial on updating tool versions. Collection inputs: the workflow editor has one Inputs type for individual datasets and three for collections; the collection input's type field must match data and downstream tool settings (Galaxy team, biostar.usegalaxy.org/p/27087). Collections keep element identifiers across steps (GTN workflow-editor tutorial). The run form cannot accept a collection for an input declared as a single dataset; collections must be declared as collection Inputs in the editor (same biostar thread). Changing an input's kind requires disconnecting all noodles and reconnecting start-to-finish to reset metadata (Galaxy help forum, help.galaxyproject.org/t/workflow-does-not-show-in-history/934). Exported .ga workflows store toolid with embedded shed version plus toolversion per step, verified in the GTN workflow-editor tutorial workflow listing.