{"record":{"id":"b3c001911e0f50c5","repo":"ansible/ansible","slug":"could-not-find-locale-tool","errorCode":null,"errorMessage":"Could not find 'locale' tool","messagePattern":"Could not find 'locale' tool","errorType":"exception","errorClass":"RuntimeWarning","httpStatus":null,"severity":"warning","filePath":"lib/ansible/module_utils/common/locale.py","lineNumber":27,"sourceCode":"def get_best_parsable_locale(module, preferences=None, raise_on_locale=False):\n    \"\"\"\n        Attempts to return the best possible locale for parsing output in English\n        useful for scraping output with i18n tools. When this raises an exception\n        and the caller wants to continue, it should use the 'C' locale.\n\n        :param module: an AnsibleModule instance\n        :param preferences: A list of preferred locales, in order of preference\n        :param raise_on_locale: boolean that determines if we raise exception or not\n                                due to locale CLI issues\n        :returns: The first matched preferred locale or 'C' which is the default\n    \"\"\"\n\n    found = 'C'  # default posix, its ascii but always there\n    try:\n        locale = module.get_bin_path(\"locale\")\n        if not locale:\n            # not using required=true as that forces fail_json\n            raise RuntimeWarning(\"Could not find 'locale' tool\")\n\n        available = []\n\n        if preferences is None:\n            # new POSIX standard or English cause those are messages core team expects\n            # yes, the last 2 are the same but some systems are weird\n            preferences = ['C.utf8', 'C.UTF-8', 'en_US.utf8', 'en_US.UTF-8', 'C', 'POSIX']\n\n        rc, out, err = module.run_command([locale, '-a'])\n\n        if rc == 0:\n            if out:\n                available = out.strip().splitlines()\n            else:\n                raise RuntimeWarning(\"No output from locale, rc=%s: %s\" % (rc, to_native(err)))\n        else:\n            raise RuntimeWarning(\"Unable to get locale information, rc=%s: %s\" % (rc, to_native(err)))\n","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/module_utils/common/locale.py#L9-L45","documentation":"Raised as RuntimeWarning by ansible.module_utils.common.locale.get_best_parsable_locale() when module.get_bin_path('locale') returns None, i.e. the `locale` binary is not on the managed host's PATH. By default (raise_on_locale=False) the warning is swallowed and 'C' is used; it only propagates when the caller passes raise_on_locale=True.","triggerScenarios":"Calling get_best_parsable_locale(module) or get_best_parsable_locale(module, raise_on_locale=True) on a minimal system (container, embedded image, chroot) that lacks /usr/bin/locale.","commonSituations":"Alpine/BusyBox or distroless containers and stripped VM images where glibc locale tooling is not installed; modules such as ansible.builtin.package or reboot-adjacent code that normalize locale before parsing command output.","solutions":["Install the locale tool on the target (apk add musl-locales / apt-get install locales / dnf install glibc-common)","Call with raise_on_locale=False (the default) to accept the 'C' fallback","For containers, bake the locale package into the image"],"exampleFix":"# before\nlocale = get_best_parsable_locale(module, raise_on_locale=True)\n\n# after\nlocale = get_best_parsable_locale(module)  # falls back to 'C' with a debug message","handlingStrategy":"fallback","validationCode":"if module.get_bin_path('locale') is None:\n    best = 'C'  # skip the call entirely on minimal systems\nelse:\n    best = get_best_parsable_locale(module)","typeGuard":null,"tryCatchPattern":"try:\n    best = get_best_parsable_locale(module, raise_on_locale=True)\nexcept RuntimeWarning:\n    best = 'C'","preventionTips":["Keep raise_on_locale=False unless output parsing truly depends on a specific locale","Install locale tooling in minimal container images used as managed targets","Write output parsing to be robust under the 'C' fallback rather than requiring UTF-8 locales"],"tags":["locale","containers","minimal-systems","ansible-module-utils"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}