ansible/ansible · warning · RuntimeWarning

Could not find 'locale' tool

Error message

Could not find 'locale' tool

What it means

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.

Source

Thrown at lib/ansible/module_utils/common/locale.py:27

def get_best_parsable_locale(module, preferences=None, raise_on_locale=False):
    """
        Attempts to return the best possible locale for parsing output in English
        useful for scraping output with i18n tools. When this raises an exception
        and the caller wants to continue, it should use the 'C' locale.

        :param module: an AnsibleModule instance
        :param preferences: A list of preferred locales, in order of preference
        :param raise_on_locale: boolean that determines if we raise exception or not
                                due to locale CLI issues
        :returns: The first matched preferred locale or 'C' which is the default
    """

    found = 'C'  # default posix, its ascii but always there
    try:
        locale = module.get_bin_path("locale")
        if not locale:
            # not using required=true as that forces fail_json
            raise RuntimeWarning("Could not find 'locale' tool")

        available = []

        if preferences is None:
            # new POSIX standard or English cause those are messages core team expects
            # yes, the last 2 are the same but some systems are weird
            preferences = ['C.utf8', 'C.UTF-8', 'en_US.utf8', 'en_US.UTF-8', 'C', 'POSIX']

        rc, out, err = module.run_command([locale, '-a'])

        if rc == 0:
            if out:
                available = out.strip().splitlines()
            else:
                raise RuntimeWarning("No output from locale, rc=%s: %s" % (rc, to_native(err)))
        else:
            raise RuntimeWarning("Unable to get locale information, rc=%s: %s" % (rc, to_native(err)))

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Install the locale tool on the target (apk add musl-locales / apt-get install locales / dnf install glibc-common)
2. Call with raise_on_locale=False (the default) to accept the 'C' fallback
3. For containers, bake the locale package into the image

Example fix

# before
locale = get_best_parsable_locale(module, raise_on_locale=True)

# after
locale = get_best_parsable_locale(module)  # falls back to 'C' with a debug message

if module.get_bin_path('locale') is None:
    best = 'C'  # skip the call entirely on minimal systems
else:
    best = get_best_parsable_locale(module)

try:
    best = get_best_parsable_locale(module, raise_on_locale=True)
except RuntimeWarning:
    best = 'C'

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No output from locale, rc=%s: %s
• Unable to get locale information, rc=%s: %s
• The value '{0}' is not a valid boolean. Valid booleans inclu
• {0} cannot be converted to a list
• ERROR: Ansible could not initialize the preferred locale: %s

AI-assisted analysis of ansible/ansible@9cf16a4aca (2026-08-15). Data as JSON: /api/errors/b3c001911e0f50c5. Report an issue: GitHub.