{"record":{"id":"cb2ceb0b2de1d87e","repo":"OpenBB-finance/OpenBB","slug":"country-value-is-not-a-valid-imf-country-code","errorCode":null,"errorMessage":"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').","messagePattern":"Country '(.+?)' 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'\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"openbb_platform/providers/imf/openbb_imf/utils/dot_helpers.py","lineNumber":120,"sourceCode":"    # Check common aliases first\n    if v_lower in common_aliases:\n        return common_aliases[v_lower]\n\n    code_set = set(list_country_choices())\n    label_to_code = get_label_to_code_map()\n\n    v_upper = value.upper()\n\n    # Check if it's a valid ISO code\n    if v_upper in code_set:\n        return v_upper\n\n    # Check if it's a valid snake_case country name\n    if v_lower in label_to_code:\n        return label_to_code[v_lower]\n\n    # Not found - raise error with helpful message\n    raise ValueError(\n        f\"Country '{value}' is not a valid IMF country code or country name. \"\n        f\"Use ISO3 codes (e.g., 'USA', 'DEU') or snake_case names (e.g., 'united_states', 'germany').\"\n    )\n\n\ndef imts_query(\n    country: str | list[str],\n    counterpart: str | list[str],\n    indicator: str | list[str],\n    freq: str = \"A\",\n    start_date: str | None = None,\n    end_date: str | None = None,\n    **kwargs,\n) -> dict:\n    \"\"\"Query the Direction of Trade (IMTS) dataset.\n    This function handles input validation for countries and counterparts.\n\n    Parameters","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/OpenBB-finance/OpenBB/blob/3e071fcc2cd9f891cac6040ae60296dba76dab46/openbb_platform/providers/imf/openbb_imf/utils/dot_helpers.py#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an ISO3 code: 'USA', 'DEU', 'CHN' — least ambiguous option.","Or use snake_case names exactly: 'united_states', 'germany'.","For aggregates use supported aliases: 'world', 'euro_area'/'eurozone', 'eu'/'european_union', or wildcard '*'/'all'."],"exampleFix":"# before\nres = imts_query(country='US', counterpart='united states', indicator='TXG_FOB_USD')\n\n# after\nres = imts_query(country='USA', counterpart='united_states', indicator='TXG_FOB_USD')","handlingStrategy":"validation","validationCode":"import country_converter  # or use the provider's own map\nALIASES = {'world', 'euro_area', 'eurozone', 'eu', 'european_union', 'all', '*'}\ndef normalize_country(v: str) -> str:\n    v = v.strip()\n    if v.lower() in ALIASES:\n        return '*' if v.lower() in ('all', '*') else v.lower()\n    iso3 = country_converter.convert(v, to='ISO3')  # raises if unknown\n    return iso3","typeGuard":"def looks_like_imf_country(v: str) -> bool:\n    v = v.strip()\n    if not v:\n        return False\n    if v.lower() in {'all', '*', 'world', 'euro_area', 'eurozone', 'eu', 'european_union'}:\n        return True\n    return len(v) == 3 and v.isalpha() and v.isupper() or v.replace('_', '').isalpha()","tryCatchPattern":"try:\n    code = transform_country(user_input)\nexcept ValueError as e:\n    # show accepted formats; suggest ISO3\n    raise ValueError(f\"{user_input!r} not recognized. Use ISO3 ('USA') or snake_case ('united_states').\") from e","preventionTips":["Standardize on ISO3 codes end-to-end.","Never pass display names with spaces — convert to snake_case or ISO3 first.","For aggregates use the documented aliases, not invented names."],"tags":["validation","imf","country-codes","dot","parameters"],"backgroundTag":null,"analyzedSha":"3e071fcc2cd9f891cac6040ae60296dba76dab46","analyzedAt":"2026-08-14T23:40:48.960Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}