OpenBB-finance/OpenBB · error · ValueError

Country '{value}' is not a valid IMF country code or country

Error message

Country '{value}' is not a valid IMF country code or country name. Use ISO3 codes (e.g., 'USA', 'DEU') or snake_case names (e.g., 'united_states', 'germany').

What it means

Raised by the country-resolution helper when the value is non-empty but matches neither an IMF area code (upper-cased), a snake_case country name in the label map, nor a known alias/group (world, eurozone, eu...). The message lists accepted formats. This is a pure input-validation failure; no request was made.

Source

Thrown at openbb_platform/providers/imf/openbb_imf/utils/dot_helpers.py:120

    # Check common aliases first
    if v_lower in common_aliases:
        return common_aliases[v_lower]

    code_set = set(list_country_choices())
    label_to_code = get_label_to_code_map()

    v_upper = value.upper()

    # Check if it's a valid ISO code
    if v_upper in code_set:
        return v_upper

    # Check if it's a valid snake_case country name
    if v_lower in label_to_code:
        return label_to_code[v_lower]

    # Not found - raise error with helpful message
    raise ValueError(
        f"Country '{value}' is not a valid IMF country code or country name. "
        f"Use ISO3 codes (e.g., 'USA', 'DEU') or snake_case names (e.g., 'united_states', 'germany')."
    )


def imts_query(
    country: str | list[str],
    counterpart: str | list[str],
    indicator: str | list[str],
    freq: str = "A",
    start_date: str | None = None,
    end_date: str | None = None,
    **kwargs,
) -> dict:
    """Query the Direction of Trade (IMTS) dataset.
    This function handles input validation for countries and counterparts.

    Parameters

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Use an ISO3 code: 'USA', 'DEU', 'CHN' — least ambiguous option.
2. Or use snake_case names exactly: 'united_states', 'germany'.
3. For aggregates use supported aliases: 'world', 'euro_area'/'eurozone', 'eu'/'european_union', or wildcard '*'/'all'.

Example fix

# before
res = imts_query(country='US', counterpart='united states', indicator='TXG_FOB_USD')

# after
res = imts_query(country='USA', counterpart='united_states', indicator='TXG_FOB_USD')

import country_converter  # or use the provider's own map
ALIASES = {'world', 'euro_area', 'eurozone', 'eu', 'european_union', 'all', '*'}
def normalize_country(v: str) -> str:
    v = v.strip()
    if v.lower() in ALIASES:
        return '*' if v.lower() in ('all', '*') else v.lower()
    iso3 = country_converter.convert(v, to='ISO3')  # raises if unknown
    return iso3

def looks_like_imf_country(v: str) -> bool:
    v = v.strip()
    if not v:
        return False
    if v.lower() in {'all', '*', 'world', 'euro_area', 'eurozone', 'eu', 'european_union'}:
        return True
    return len(v) == 3 and v.isalpha() and v.isupper() or v.replace('_', '').isalpha()

try:
    code = transform_country(user_input)
except ValueError as e:
    # show accepted formats; suggest ISO3
    raise ValueError(f"{user_input!r} not recognized. Use ISO3 ('USA') or snake_case ('united_states').") from e

When it happens

Trigger: country='United States of America (USA)' (display name with spaces/parens), country='US' (2-letter code instead of ISO3), country='united states' (spaces instead of underscores), misspellings like 'germany '.strip() variants not in the map.

Common situations: Feeding UI dropdown labels straight into the API; assuming ISO2 codes work; mixing formats from other providers (some accept 'united states' with spaces); stale maps after new countries are renamed.

Related errors

• Country value cannot be empty.
• Country and counterpart parameters cannot be empty.
• Frequency must be one of 'A', 'Q', or 'M'.
• Invalid {name}(s): {', '.join(invalid)}
• No valid port_code provided.

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