OpenBB-finance/OpenBB · error · ValueError

Invalid value(s) for dimension '{dim_id}': {invalid_values}.

Error message

Invalid value(s) for dimension '{dim_id}': {invalid_values}. Given prior selections {prior_selections}, available values are: {display_values}

What it means

Progressive-dimension validation error from the IMF table builder: a user-supplied value for a dimension (e.g. COUNTRY='XX') is not in the set of values the SDMX builder reports as available, given the dimensions already selected before it in the dimension order. It exists to fail fast with context instead of returning an empty or confusing API response.

Source

Thrown at openbb_platform/providers/imf/openbb_imf/utils/table_builder.py:542

                            if isinstance(user_value, str) and "+" in user_value
                            else [user_value]
                        )
                        invalid_values = [
                            v
                            for v in user_values
                            if v not in available_values and v != "*"
                        ]

                        if invalid_values:
                            # Build prior selections for context
                            prior_selections = {
                                d: normalized_kwargs.get(d)
                                for d in dims_in_order
                                if d in normalized_kwargs
                                and dims_in_order.index(d) < dims_in_order.index(dim_id)
                            }
                            display_values = sorted(available_values)
                            raise ValueError(
                                f"Invalid value(s) for dimension '{dim_id}': {invalid_values}. "
                                f"Given prior selections {prior_selections}, "
                                f"available values are: {display_values}"
                            )

                    builder.set_dimension((dim_id, user_value))
                    fetch_kwargs[dim_id] = user_value
                # If this dimension has hierarchy codes, filter them against available
                elif dim_id in dimension_codes:
                    # Check if user explicitly provided this dimension (e.g., INDICATOR='*')
                    # If so, use their value for the builder but still process hierarchy codes
                    user_override = normalized_kwargs.get(dim_id)
                    codes = dimension_codes[dim_id]
                    available_options = builder.get_options_for_dimension(dim_id)
                    available_values = {opt["value"] for opt in available_options}
                    filtered_codes = [c for c in codes if c in available_values]
                    # If no exact matches, try prefix matching for INDICATOR dimension
                    # Hierarchies may use base codes (FSI688_TREGK) while dataflow has

View on GitHub (pinned to 3e071fcc2c)

Solutions

Read the message: it lists the exact available values for the failing dimension - pick one of those instead of your current value.
Check earlier selections reported as prior_selections; relax or correct one of them, since availability is conditional on those.
Normalize codes (uppercase, ISO-3 country codes, official SDMX indicator IDs) before passing them.
If the value should be valid, refresh provider metadata/caches - IMF codelists may have changed.

Example fix

# before
obb.economy.imf.fetch(dataset='IFS', parameters={'COUNTRY': 'USS', 'INDICATOR': 'EDP'})
# after - use a country code from the reported available values
obb.economy.imf.fetch(dataset='IFS', parameters={'COUNTRY': 'USA', 'INDICATOR': 'EDP'})

Defensive patterns

Strategy: validation

Validate before calling

# Validate dimension values against the table's own options before fetching
params = {'COUNTRY': 'USA', 'INDICATOR': 'EDP'}
options = obb.economy.imf.dimension_options(dataset='IFS', dimension='COUNTRY')  # or equivalent
valid = {o.value for o in options.results}
bad = {k: v for k, v in params.items() if k == 'COUNTRY' and v not in valid}
assert not bad, f'Invalid dimension values: {bad}; choose from {sorted(valid)[:10]}...'

Type guard

def is_valid_dimension_value(value: str, available: set[str]) -> bool:
    """True when value is an available code or the wildcard."""
    return value == '*' or value in available

Try / catch

try:
    res = obb.economy.imf.fetch(dataset='IFS', parameters=params)
except ValueError as e:
    if 'Invalid value(s) for dimension' in str(e):
        # message lists valid values - parse and re-prompt user / pick first valid
        handle_invalid_dimension(str(e))
    raise

Prevention

Uppercase and normalize codes before passing
Never mix indicator codes across datasets
Build parameter dicts from discovered codelist options, not hardcoded strings

When it happens

Trigger: Passing a dimension value that is invalid for the table given earlier selections - e.g. fetch(..., COUNTRY='EURO') where that code isn't in the codelist, or an INDICATOR code that doesn't exist once COUNTERPART_AREA or frequency was fixed. Raised while iterating dims_in_order and normalizing kwargs against builder.get_options_for_dimension().

Common situations: Typos or outdated ISO/country codes; using indicator codes from one IMF dataset in another; case mismatches ('us' vs 'US'); combining dimension filters that are mutually exclusive for the chosen table.

Related errors

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/8f12bce1643faeba. Report an issue: GitHub.