OpenBB-finance/OpenBB · error · ValueError

Country code is not supported by IMF Port Watch.

Error message

Country code is not supported by IMF Port Watch.

What it means

Raised by the Port Watch country-code resolver: the uppercased country code is not among the {value: label} pairs returned by list_countries(), so the IMF Port Watch API has no matching country. It is an input-validation ValueError occurring before any HTTP request.

Source

Thrown at openbb_platform/providers/imf/openbb_imf/utils/port_watch_helpers.py:57

def map_port_country_code(country_code: str) -> str:
    """Map the 3-letter country code to the full country name.

    Parameters
    ----------
    country_code : str
        The 3-letter ISO country code (e.g., "USA" for the United States).

    Returns
    -------
    str
        The full country name, without accents, corresponding to the provided country code.
    """
    cc = country_code.upper()
    countries = list_countries()
    code_to_country = {country["value"]: country["label"] for country in countries}
    if cc not in code_to_country:
        raise ValueError("Country code is not supported by IMF Port Watch.")

    return code_to_country.get(cc, cc)


def get_port_ids_by_country(country_code: str) -> str:
    """Get all port IDs for a specific country. The country code should be a 3-letter ISO code.

    Parameters
    ----------
    country_code : str
        The 3-letter ISO country code (e.g., "USA" for the United States).

    Returns
    -------
    str
        A list of port IDs as a comma-separated string.
    """
    ports = get_ports()

View on GitHub (pinned to 3e071fcc2c)

Solutions

1. Use the 3-letter ISO 3166-1 alpha-3 code (e.g. 'USA', 'CHN', 'DEU').
2. If you hold alpha-2 codes, map them to alpha-3 (e.g. via pycountry) before calling.
3. Validate against list_countries() values up front and show the supported set on failure.

Example fix

# before
name = get_country_name_from_code('US')

# after
import pycountry
c = pycountry.countries.get(alpha_2='US')
name = get_country_name_from_code(c.alpha_3)  # 'USA'

from openbb_imf.utils.port_watch_helpers import list_countries
SUPPORTED = {c['value'] for c in list_countries()}

def normalize_country(code: str) -> str:
    cc = code.strip().upper()
    if len(cc) == 2:
        import pycountry
        cc = pycountry.countries.get(alpha_2=cc).alpha_3
    if cc not in SUPPORTED:
        raise ValueError(f'{code!r} unsupported; use 3-letter ISO codes')
    return cc

def is_supported_country_code(code: object) -> bool:
    if not isinstance(code, str) or len(code.strip()) != 3:
        return False
    return code.strip().upper() in {c['value'] for c in list_countries()}

try:
    name = get_country_name_from_code(code)
except ValueError as e:
    if 'not supported' in str(e):
        raise InvalidInput('Provide a 3-letter ISO 3166-1 alpha-3 code') from e
    raise

When it happens

Trigger: Passing a 2-letter code ('US') instead of the required 3-letter ISO code ('USA'); non-ISO or retired codes ('ZAR'); codes of territories Port Watch does not cover; codes with whitespace or punctuation.

Common situations: Users habitually typing ISO 3166-1 alpha-2 codes, forwarding World Bank alpha-2 codes into a Port Watch call, or passing a currency code by mistake.

Related errors

• At least one extension type must be selected.
• Results not found.
• Please install polars: `pip install polars pyarrow` to use
• Either port_id or country_code must be provided.
• Incorrect email or password

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