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