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

Stops Galaxy workflows from breaking on tool updates: switch each step to an explicit installed tool version via the editor's version dropdown or Workflow Options -> Upgrade workflow; declare collection inputs with the correct list/paired/list:paired type; and repair stalled runs by disconnecting and reconnecting all noodles start-to-finish after any input change.

Exact reference: {"kind":"skill_version","skill_id":"skl_Uet6taNro0DiwhQ4UOApOQ","version_id":"skv_TG0OH5Uy6OnuocdDBQCl9A"}

Applicability: [{"constraint":"Building or editing a Galaxy workflow that must reproduce results over time or across servers","technology":"Galaxy","version_scheme":"unknown"},{"constraint":"A Galaxy workflow that broke, stalled, or changed behavior after a tool or server update","technology":"Galaxy","version_scheme":"unknown"},{"constraint":"Workflow runs that fail or never schedule because a step received a dataset where it expected a collection, or a collection of the wrong structure","technology":"Galaxy","version_scheme":"unknown"},{"constraint":"Reviewing an exported .ga workflow file or workflow pull request for reproducibility","technology":"Galaxy","version_scheme":"unknown"}]

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


## Supporting basis and limitations

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 (test_editor_tool_upgrade in docs.galaxyproject.org), which also verifies steps store tool_version 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 tool_id with embedded shed version plus tool_version per step, verified in the GTN workflow-editor tutorial workflow listing.

## Change and rationale

New skill covering the two dominant Galaxy workflow failure modes: unpinned tool versions silently shifting when servers install updates, and dataset-vs-collection input type mismatches that stall or break workflow invocations. Includes concrete editor steps (per-step version switch, bulk upgrade, collection input types), mismatch diagnosis and repair (noodle reset), and workflow-file (.ga tool_version) review notes.

Galaxy workflow breakage from tool updates and input-kind mismatches is a recurrent, concrete pain point documented across Galaxy Training Network tutorials, the Galaxy help forum, and Galaxy's own selenium test suite. There is a verified, checkable UI procedure for each fix (version dropdown items like 'Switch to 0.2', 'Upgrade workflow' in Workflow Options, three collection Input types, disconnect/reconnect noodles to reset metadata, tool_version per step in exported .ga). A skill capturing exactly these steps saves users from rediscovering them through forum threads.