{"record":{"id":"dedaeb98117143c3","repo":"OpenBB-finance/OpenBB","slug":"invalid-country-value-accepts-iso-3166-1-alp","errorCode":null,"errorMessage":"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').","messagePattern":"Invalid country: '(.+?)'\\. 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'\\)\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"openbb_platform/core/openbb_core/provider/utils/country_utils.py","lineNumber":194,"sourceCode":"            If the country cannot be found.\n        \"\"\"\n        val = str(value).strip()\n\n        if \"_\" in val:\n            val = val.replace(\"_\", \" \")\n\n        lookup_key = val.lower()\n        if lookup_key in _COUNTRY_LOOKUP:\n            return _COUNTRY_LOOKUP[lookup_key]\n\n        if val in _COUNTRY_LOOKUP:\n            return _COUNTRY_LOOKUP[val]\n\n        ascii_key = _strip_accents(lookup_key)\n        if ascii_key in _COUNTRY_LOOKUP:\n            return _COUNTRY_LOOKUP[ascii_key]\n\n        raise ValueError(\n            f\"Invalid country: '{value}'. \"\n            \"Accepts ISO 3166-1 alpha-2 codes (e.g., 'US'), \"\n            \"alpha-3 codes (e.g., 'USA'), \"\n            \"or country names (e.g., 'United States', 'united_states').\"\n        )\n\n    @property\n    def alpha_2(self) -> str:\n        \"\"\"ISO 3166-1 alpha-2 code (e.g., 'US').\"\"\"\n        return self._country_data[\"alpha_2\"]\n\n    @property\n    def alpha_3(self) -> str:\n        \"\"\"ISO 3166-1 alpha-3 code (e.g., 'USA').\"\"\"\n        return self._country_data[\"alpha_3\"]\n\n    @property\n    def name(self) -> str:","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/OpenBB-finance/OpenBB/blob/3e071fcc2cd9f891cac6040ae60296dba76dab46/openbb_platform/core/openbb_core/provider/utils/country_utils.py#L176-L212","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Use an exact ISO 3166-1 alpha-2 ('US'), alpha-3 ('USA'), or the table's canonical name ('United States')","Normalize informal names on your side before the call (e.g. map 'UK'->'GB', 'UAE'->'ARE')","Strip diacritics and underscores yourself if the input is exotic: 'Côte d'Ivoire' -> \"cote d'ivoire\"","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"],"exampleFix":"# before\nres = await obb.equity.search(country=\"UK\")  # not ISO 3166-1 -> ValueError\n\n# after\nres = await obb.equity.search(country=\"GB\")  # ISO alpha-2 for the United Kingdom","handlingStrategy":"validation","validationCode":"from openbb_core.provider.utils.country_utils import _COUNTRY_LOOKUP\n\ndef resolve_country_or_none(code: str):\n    k = code.lower()\n    return _COUNTRY_LOOKUP.get(k) or _COUNTRY_LOOKUP.get(code) or _COUNTRY_LOOKUP.get(_strip_accents(k))\n\nif resolve_country_or_none(user_country) is None:\n    user_country = {\"UK\": \"GB\", \"UAE\": \"ARE\"}.get(user_country.upper(), \"US\")","typeGuard":"def is_known_country(v: str) -> bool:\n    from openbb_core.provider.utils.country_utils import _COUNTRY_LOOKUP\n    k = v.lower()\n    return k in _COUNTRY_LOOKUP or v in _COUNTRY_LOOKUP","tryCatchPattern":"from pydantic import ValidationError\n\ntry:\n    res = await obb.equity.search(country=country)\nexcept ValidationError as e:\n    if any(\"Invalid country\" in str(err[\"msg\"]) for err in e.errors()):\n        res = await obb.equity.search(country=\"US\")  # documented fallback\n    else:\n        raise","preventionTips":["Prefer ISO 3166-1 alpha-2 codes at every boundary; store names only for display","Maintain a small alias map for informal names your users type (UK, UAE, Korea, Holland)","Validate free-text countries against the packaged lookup before calling OpenBB endpoints"],"tags":["validation","iso-3166","country","pydantic"],"backgroundTag":null,"analyzedSha":"3e071fcc2cd9f891cac6040ae60296dba76dab46","analyzedAt":"2026-08-14T23:40:48.960Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}