OpenBB-finance/OpenBB · error · ValueError

Unknown country/region: '{c}' for {commodity}. Valid countri

Error message

Unknown country/region: '{c}' for {commodity}. Valid countries: {valid_keys}. Valid regions: {valid_regions}

What it means

The fallback branch when the input matches neither an ISO code (COUNTRY_TO_REGION), a known region, the 'eu' shorthand, nor a COUNTRIES name key. It reports both the commodity's valid countries (snake_cased) and the global REGIONS keys, since the value could be intended as either.

Source

Thrown at openbb_platform/providers/government_us/openbb_government_us/utils/psd_data_downloader.py:385

                country_codes.append(code)
            # Check if it's a country name (snake_case)
            elif country_key in COUNTRIES:
                code = COUNTRIES[country_key]
                # Validate against commodity-specific countries
                if valid_country_codes and code not in valid_country_codes:
                    valid_keys = get_valid_country_keys()
                    raise ValueError(
                        f"Country '{c}' is not available for {commodity}. Valid countries: {valid_keys}"
                    )
                selected_country_codes.append(code)
                country_codes.append(code)
            else:
                # Unknown country/region
                valid_keys = sorted(
                    [k.lower().replace(" ", "_") for k in valid_countries_map]
                )
                valid_regions = list(REGIONS.keys())
                raise ValueError(
                    f"Unknown country/region: '{c}' for {commodity}. "
                    + f"Valid countries: {valid_keys}. Valid regions: {valid_regions}"
                )

    # If aggregate_region is True, expand appropriately
    if aggregate_region:
        if "R00" in selected_region_codes:
            # "world" selected - fetch all regional aggregates + any specific countries
            country_codes = (
                list(REGIONS.values()) + selected_country_codes
            )  # R00, R01, ... R18 + specific countries
            country_codes = list(set(country_codes))  # Dedupe
        elif selected_region_codes:
            # Specific regions selected - add World + those regions + any countries
            country_codes = ["R00"] + selected_region_codes + selected_country_codes
            country_codes = list(set(country_codes))  # Dedupe
        elif selected_country_codes:
            # Only countries selected - add World + their regions

View on GitHub (pinned to 3e071fcc2c)

Solutions

Use an exact key from the error's valid countries list or a valid region code (R00..R18 / 'world').
Normalize input to lower snake_case before calling.
Update the provider if a legitimately named country is missing from COUNTRIES.

Example fix

# before
fetch(commodity="cotton", country="Unitd States")

# after
fetch(commodity="cotton", country="united_states")

Defensive patterns

Strategy: validation

Validate before calling

from openbb_government_us.utils.psd_data_downloader import COUNTRIES, COUNTRY_TO_REGION, REGIONS

def classify_country_input(c: str) -> str | None:
    key = c.lower().replace(" ", "_")
    if key in ("eu",): return "region"
    if key in REGIONS or key.upper() in REGIONS: return "region"
    if c.upper() in COUNTRY_TO_REGION: return "code"
    if key in COUNTRIES: return "name"
    return None  # will raise 'Unknown country/region'

Type guard

def is_recognized_country_or_region(c: str) -> bool is not None and isinstance(c, str) and classify_country_input(c) is not None

Prevention

Normalize to lower snake_case and check against COUNTRIES/REGIONS before calling.
Suggest close matches when user input fails recognition (fuzzy match over valid keys).

When it happens

Trigger: Typos ('unitd_states'), country names not in the map (alternative spellings, former names), or region names passed in the wrong form (e.g. 'Sub-Saharan Africa' instead of its R-code).

Common situations: Free-text country input; non-English or alternate romanizations; stale maps missing newly recognized countries.

Related errors

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