You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Also strange is that when editing the dbkey the UI shows unspecified is shown 2x.
Steps to Reproduce
Load samtools stats
Upload a sam/bam file
Select "Use a built-in genome" in reference conditional
Observe that there is no selection possible
Set/unset dbkey of the sam file and see difference
Expected Behavior
All choices are shown if there is no dbkey set.
Context
The tool affected is samtools_stats, which uses a macro optional_reference from IUC tools.
The select param is inside a conditional (addref_cond) under the when value="cached" case,
while the referenced input data param is at the tool's top level.
If options.length === 0, the "No options available" alert is shown instead of the dropdown.
Tool Structure (samtools_stats)
The affected select parameter is inside a conditional (non-default case):
<inputs>
<paramname="input"type="data"format="sam,bam,cram" /> <!-- top-level -->
...
<conditionalname="addref_cond">
<paramname="addref_select"type="select">
<optionvalue="no">No</option> <!-- DEFAULT -->
<optionvalue="history">Use a genome/index from the history</option>
<optionvalue="cached">Use a built-in genome</option>
</param>
<whenvalue="no"/>
<whenvalue="history">...</when>
<whenvalue="cached">
<paramname="ref"type="select">
<optionsfrom_data_table="fasta_indexes">
<filtertype="data_meta"ref="input"key="dbkey"column="dbkey"/>
</options>
<validatortype="no_options"message="No reference genome is available..."/>
</param>
</when>
</conditional>
</inputs>
On initial load, the default case is "no", so the "cached" case is inactive during populate_model.
Theories
Theory 1 (MOST PROBABLE): Exception in populate_model causes silent fallback to empty options
When populate_model processes the inactive "cached" conditional case, it creates current_state = {} (empty dict since it's not the active case). Inside the recursive call, other_values = ExpressionContext({}, parent_context). The parent context should still have the input HDA via the ExpressionContext chain.
However, if get_initial_value or to_dict throws ANY exception (e.g., the no_options validator raising an error during option generation, a database session issue, or a type mismatch), the generic except Exception handler fires:
tool_dict=input.to_dict(request_context) # without other_values!
This results in empty options because the data_meta filter can't find the referenced dataset.
The no_options validator on the select would cause validation to fail on the options when they're empty, but it runs inside get_initial_value via get_options, which catches ImplicitConversionRequired but not general exceptions like those from validators.
Theory 2: Conditional inactive case has stale/missing state for referenced params
In populate_model, for inactive conditional cases, current_state = {}. The other_values chain should resolve input from the parent context, but there might be an edge case where the ExpressionContext lookup doesn't propagate correctly for some parameter configurations.
The fact that set/unset dbkey "fixes" it suggests the rebuild POST after the explicit action sends a different/more complete form state that avoids the error path.
Theory 3: The initial GET request doesn't include dataset reference in incoming params
On the initial GET /api/tools/{tool_id}/build, incoming is essentially empty (just query string params). The populate_state function uses get_initial_value for the data param, which selects the most recent matching HDA. However, if the from_json call in check_param processes the value differently on initial GET vs POST rebuild, the state could contain different types of values.
On GET: state['input'] = HDA object (from get_initial_value)
On POST: state['input'] = HDA object (resolved from {values: [{id, src}]})
Both should be HDA objects, so this theory is less likely unless there's a subtle type difference.
Relevant Recent Commits
0f72943993d "Skip data_meta filter in run form" - Added short-circuit for workflow run form (USE_HISTORY mode). Does NOT apply to regular tool form.
eae78408fbd "Fix dynamic filter option access when building command line" - Made trans parameter optional in filter_options to fix crash.
These changes are specifically for workflow contexts and shouldn't affect the regular tool form.
Key Files
/lib/galaxy/tools/parameters/dynamic_options.py - DataMetaFilter class (lines 146-256), _get_ref_data function (lines 1053-1086)
/lib/galaxy/tools/parameters/populate_model.py - populate_model function, especially exception handling (lines 54-68)
This is a functional breakage that prevents users from using built-in/cached reference genomes for tools that use the data_meta filter pattern with dbkey. It does NOT cause data loss, crashes, or security issues, but it renders a core workflow impossible through the UI.
Blast Radius: Broad - Affects All Users of Affected Tools
Scope: Any tool using the <filter type="data_meta" ref="..." key="dbkey" column="dbkey"/> pattern with from_data_table inside a conditional. This is the standard IUC macro pattern used in the optional_reference and mandatory_reference macros.
Affected tools include: samtools_stats, samtools_markdup, samtools_calmd, and many other samtools/bioinformatics tools that use cached genome references. This is a VERY common pattern in the Galaxy tool ecosystem.
Confirmed on: Main, AU, EU Galaxy servers (per IUC issue #7718)
Environments affected: All browsers, all operating systems, Galaxy 25.1
Workaround Existence: Acceptable but Inconvenient
Two workarounds exist:
Set then unset the dbkey on the input dataset - This clears the state and allows all options to appear. Works reliably but requires the user to know about it.
Use "genome from history" instead of "built-in genome" - Upload/provide the reference FASTA directly. Works but defeats the purpose of having cached genomes.
Set the dbkey explicitly on the input dataset to match the desired genome - This shows the correct filtered option.
Regression Status: Likely New in 25.x
Tool tests pass (the backend logic is correct in the test execution path)
The issue is specific to the UI form building path
Multiple recent commits have modified related code paths in dynamic_options.py including 0f72943993d (Skip data_meta filter in run form) and eae78408fbd (Fix dynamic filter option access when building command line)
The issue was first reported against Galaxy 25.1 and confirmed on major public servers
No prior reports of this behavior suggest it's a regression, not a long-standing issue
User Impact Signals
IUC Issue #7718: Opened by a different user (shiltemann), confirmed on Main/AU/EU servers
GTN Impact: A Galaxy Training Network issue was filed (training-material#6658) because users following tutorials can't complete exercises
Galaxy Issue #21904: Filed by bernt-matthias (IUC maintainer), indicating this is blocking tool maintenance work
No comments yet on the Galaxy issue, but the GTN connection means this is affecting many new users following tutorials
Recommendation: Next Release / High Priority Fix
NOT a hotfix - There's a viable workaround (set/unset dbkey) and no data loss risk
Should be fixed for next release - This affects a very common tool pattern, impacts training materials, and makes Galaxy look broken for new users
Priority: High within the normal release cycle. The GTN training impact elevates the urgency since it affects user onboarding
Fix should include a regression test that validates the tool form JSON response for a data_meta filtered select when the input dataset has unset dbkey
Based on code research, the most probable root cause is in populate_model.py's exception handling. When the select parameter with data_meta filter is inside a non-active conditional case, any exception during get_initial_value() or to_dict() triggers the generic except Exception handler which calls to_dict(request_context) WITHOUT other_values. This causes the data_meta filter to not find the referenced dataset, returning empty options.
The secondary contributing factor may be in how the no_options validator interacts with the dynamic options generation. When options are generated for the inactive conditional case but the validator fires, it could raise an exception that gets caught by the generic handler.
Debugging Strategy (First Step)
Before implementing a fix, the exact exception needs to be identified:
Add logging: In populate_model.py line 66-68, the log.exception() call should already log the exception. Check Galaxy server logs for the message "tools::to_json() - Skipping parameter expansion 'ref'" when loading samtools_stats.
Reproduce locally: Load the dbkey_filter_input test tool form via the API and inspect the response JSON:
The generic except Exception handler at lines 66-68 silently swallows exceptions and falls back to a degraded to_dict call without other_values. This means any exception during option generation results in empty options with no user-visible error.
Proposed fix: When the generic exception handler fires, preserve other_values in the fallback to_dict call:
This is the safest minimal fix. Even if get_initial_value failed, to_dict should still be able to generate options with the correct other_values.
If the exception occurs IN to_dict itself (not in get_initial_value), then passing other_values again might cause the same exception. In that case, a two-step fallback:
Currently, when _get_ref_data raises KeyError or ValueError, the filter returns [] (empty list). This is overly aggressive -- when the reference can't be found, the behavior should be the same as when the metadata is unset: return ALL options.
Proposed fix: Change the error handling in DataMetaFilter.filter_options:
try:
ref=_get_ref_data(other_values, self.ref_name)
exceptKeyError:
log.warning(f"could not filter by metadata: {self.ref_name} unknown")
returncopy.deepcopy(list(options)) # Return all options instead of emptyexceptValueError:
log.warning(f"could not filter by metadata: {self.ref_name} not a data or collection parameter")
returncopy.deepcopy(list(options)) # Return all options instead of empty
This is semantically correct: if we can't determine the metadata value to filter by, we should show all options (same as when metadata is unset). This matches the existing behavior at line 241-242 where len(meta_value) == 0 returns all options.
Caution: This changes long-standing behavior. Some tools might rely on the empty-return behavior when the reference is missing. However, returning all options is the documented expected behavior ("present all choices if the user gives no dbkey").
Approach C: Combined fix (Recommended)
Apply both fixes:
Fix populate_model.py exception handler to preserve other_values
Fix DataMetaFilter.filter_options to return all options when ref is unavailable
This provides defense in depth: even if one fix doesn't address the exact scenario, the other will catch it.
Test DataMetaFilter with missing ref: Verify that when other_values doesn't contain the referenced dataset, filter_options returns all options (not empty).
Test DataMetaFilter with unset dbkey: Verify that when the referenced dataset has dbkey="?", filter_options returns all options.
Test populate_model exception handling: Verify that when get_initial_value throws, the fallback to_dict still gets other_values.
Integration Tests
Test tool form build with dbkey_filter_input test tool:
GET /api/tools/dbkey_filter_input/build with a dataset that has dbkey="?"
Verify the select options are NOT empty
Existing test at test/functional/tools/dbkey_filter_input.xml test 2 already covers the execution path but NOT the form build path
Test tool form rebuild after conditional switch:
Build a tool form for a tool with data_meta filter inside a conditional
Switch the conditional to the filtered case
Verify options are populated
Selenium/Browser Tests
Test the user-facing workflow described in the issue:
Upload a BAM file without dbkey
Open samtools stats tool form
Switch to "Use a built-in genome"
Verify genome options are shown
Migration Considerations
None. This is a behavior fix with no database or configuration changes.
Backwards Compatibility
Approach A (populate_model): No backwards compatibility concerns. The exception handler is a fallback that should ideally never fire.
Approach B (DataMetaFilter): Minor behavior change -- tools that previously got empty options when the ref was missing will now get all options. This is arguably the correct behavior and matches documentation, but could theoretically change behavior for tools that rely on the empty state.
When a dataset with unset dbkey (dbkey="?") is used as input to a tool that has a data_meta filtered select (e.g., samtools_stats with a cached reference genome), the UI incorrectly shows "No options available" instead of listing all available options. The backend logic for handling unset dbkey is correct (and tool tests pass), so the bug is in the tool form building path. The most probable root cause is in populate_model.py's exception handling: when the select parameter is inside a non-active conditional case, any exception during option generation triggers a fallback that discards the other_values context, causing the data_meta filter to lose its dataset reference and return empty options. A secondary contributing factor is that DataMetaFilter.filter_options returns an empty list when the referenced dataset can't be found, whereas it should return all options (matching the behavior when metadata is simply unset). The recommended fix addresses both issues: (1) preserve other_values in the exception fallback, and (2) return all options when the dataset reference is unavailable.
Importance Assessment Summary
Attribute
Assessment
Severity
Medium-High (functional breakage)
Blast Radius
Broad - affects all tools using the IUC optional_reference/mandatory_reference macro pattern (samtools suite, BWA, Bowtie2, etc.)
Regression Status
Likely new in 25.x based on timing and recent related commits
Workaround
Acceptable - set then unset dbkey on input dataset, or use genome from history
User Impact
High - confirmed on Main/AU/EU servers, blocking GTN tutorials
Priority Recommendation
Fix for next release, high priority within normal cycle
Questions for Group Discussion
Reproduction: Can someone reproduce this with the built-in dbkey_filter_input test tool, or only with IUC tools? If the test tool works, the issue might be specific to the conditional nesting pattern used in optional_reference.
Exception logging: Has anyone checked Galaxy server logs for "tools::to_json() - Skipping parameter expansion" messages when loading affected tools? This would confirm Theory 1 (exception handler fallback).
Scope of Approach B: Changing DataMetaFilter.filter_options to return all options (instead of []) when the reference dataset is unavailable -- does anyone know of tools that intentionally rely on the empty-return behavior?
Validator interaction: The no_options validator on the select fires when options are empty. Could this validator be causing a secondary exception during get_initial_value that triggers the populate_model fallback? Should we check if the validator interacts poorly with the option generation for inactive conditional cases?
Duplicate dbkey entry: The reporter notes "unspecified is shown 2x" when editing dbkey. Is this a separate client-side UI issue or related to the same root cause?
Effort Estimate and Difficulty
Aspect
Estimate
Total effort
~1 day (4-7 hours)
Debugging/confirmation
1-2 hours
Implementation
1-2 hours
Testing
2-3 hours
Difficulty
Medium - the code paths are well-understood but the exact exception triggering the fallback needs to be identified through debugging
Recreating
Easy on any Galaxy instance with cached genomes - just load samtools stats with a BAM file that has unset dbkey
Testing
Medium - needs both API-level test (form build JSON validation) and ideally a Selenium test for the full user workflow
