OpenBB-finance/OpenBB · error · ValueError

Invalid country: '{value}'. Accepts ISO 3166-1 alpha-2 codes

Error message

Invalid country: '{value}'. Accepts ISO 3166-1 alpha-2 codes (e.g., 'US'), alpha-3 codes (e.g., 'USA'), or country names (e.g., 'United States', 'united_states').

What it means

Raised by Country.__new__._lookup_country (country_utils.py) when the value cannot be resolved against the built-in ISO 3166 lookup table. The lookup tries lowercase, exact-case, and accent-stripped lowercase forms of alpha-2 ('US'), alpha-3 ('USA'), and country names ('United States', 'united_states'); exhaustion of all three raises this ValueError. Country is used as a annotated Pydantic type, so the error surfaces during model validation when a 'country' parameter is normalized.

Source

Thrown at openbb_platform/core/openbb_core/provider/utils/country_utils.py:194

            If the country cannot be found.
        """
        val = str(value).strip()

        if "_" in val:
            val = val.replace("_", " ")

        lookup_key = val.lower()
        if lookup_key in _COUNTRY_LOOKUP:
            return _COUNTRY_LOOKUP[lookup_key]

        if val in _COUNTRY_LOOKUP:
            return _COUNTRY_LOOKUP[val]

        ascii_key = _strip_accents(lookup_key)
        if ascii_key in _COUNTRY_LOOKUP:
            return _COUNTRY_LOOKUP[ascii_key]

        raise ValueError(
            f"Invalid country: '{value}'. "
            "Accepts ISO 3166-1 alpha-2 codes (e.g., 'US'), "
            "alpha-3 codes (e.g., 'USA'), "
            "or country names (e.g., 'United States', 'united_states')."
        )

    @property
    def alpha_2(self) -> str:
        """ISO 3166-1 alpha-2 code (e.g., 'US')."""
        return self._country_data["alpha_2"]

    @property
    def alpha_3(self) -> str:
        """ISO 3166-1 alpha-3 code (e.g., 'USA')."""
        return self._country_data["alpha_3"]

    @property
    def name(self) -> str:

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Use an exact ISO 3166-1 alpha-2 ('US'), alpha-3 ('USA'), or the table's canonical name ('United States')
2. Normalize informal names on your side before the call (e.g. map 'UK'->'GB', 'UAE'->'ARE')
3. Strip diacritics and underscores yourself if the input is exotic: 'Côte d'Ivoire' -> "cote d'ivoire"
4. If a legitimately missing/renamed country is suspected, check the packaged lookup table in openbb_core.provider.utils.country_utils and open a GitHub issue / update the data script

Example fix

# before
res = await obb.equity.search(country="UK")  # not ISO 3166-1 -> ValueError

# after
res = await obb.equity.search(country="GB")  # ISO alpha-2 for the United Kingdom

from openbb_core.provider.utils.country_utils import _COUNTRY_LOOKUP

def resolve_country_or_none(code: str):
    k = code.lower()
    return _COUNTRY_LOOKUP.get(k) or _COUNTRY_LOOKUP.get(code) or _COUNTRY_LOOKUP.get(_strip_accents(k))

if resolve_country_or_none(user_country) is None:
    user_country = {"UK": "GB", "UAE": "ARE"}.get(user_country.upper(), "US")

def is_known_country(v: str) -> bool:
    from openbb_core.provider.utils.country_utils import _COUNTRY_LOOKUP
    k = v.lower()
    return k in _COUNTRY_LOOKUP or v in _COUNTRY_LOOKUP

from pydantic import ValidationError

try:
    res = await obb.equity.search(country=country)
except ValidationError as e:
    if any("Invalid country" in str(err["msg"]) for err in e.errors()):
        res = await obb.equity.search(country="US")  # documented fallback
    else:
        raise

When it happens

Trigger: Passing a non-ISO country string ('Russia' may be absent depending on the table edition, 'UAE', 'Korea'), an unaccented spelling not present in the table, a 2-letter code that is not ISO alpha-2 ('AE' works, 'ZZ' does not), or a non-string (int) that fails all dict lookups.

Common situations: Free-text country names from users or upstream CSVs ('U.S.A.', 'UK' vs 'GB'), informal acronyms ('UAE' instead of 'ARE'/'United Arab Emirates'), or codes from a different standard (ISO 4217 currency codes like 'USD' passed by mistake).

Related errors

• At least one extension type must be selected.
• Incorrect email or password
• Charting is not installed. Please install `openbb-charting`.
• Invalid command : route={route}
• OBBject Extension Error -> An OBBject extension that modif

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