ansible/ansible · error · AnsibleOptionsError

Error reading config file(%s) because the config file was no

Error message

Error reading config file(%s) because the config file was not utf8 encoded: %s

What it means

AnsibleOptionsError raised while parsing an INI config file when decoding the raw bytes with to_text(..., errors='surrogate_or_strict') raises UnicodeError — the file is not valid UTF-8. Ansible requires UTF-8 (or plain ASCII) config files, and this guard fails fast at load time with the file path and underlying codec error embedded in the message.

Source

Thrown at lib/ansible/config/manager.py:437

        raise AnsibleError(
            "Missing base YAML definition file (bad install?): %s" % to_native(yml_file))

    def _parse_config_file(self, cfile=None):
        """ return flat configuration settings from file(s) """
        # TODO: take list of files with merge/nomerge

        if cfile is None:
            cfile = self._config_file

        ftype = get_config_type(cfile)
        if cfile is not None:
            if ftype == 'ini':
                self._parsers[cfile] = configparser.ConfigParser(inline_comment_prefixes=(';',))
                with open(to_bytes(cfile), 'rb') as f:
                    try:
                        cfg_text = to_text(f.read(), errors='surrogate_or_strict')
                    except UnicodeError as e:
                        raise AnsibleOptionsError("Error reading config file(%s) because the config file was not utf8 encoded: %s" % (cfile, to_native(e)))
                try:
                    self._parsers[cfile].read_string(cfg_text)
                except configparser.Error as e:
                    raise AnsibleOptionsError("Error reading config file (%s): %s" % (cfile, to_native(e)))
            # FIXME: this should eventually handle yaml config files
            # elif ftype == 'yaml':
            #     with open(cfile, 'rb') as config_stream:
            #         self._parsers[cfile] = yaml_load(config_stream)
            else:
                raise AnsibleOptionsError("Unsupported configuration file type: %s" % to_native(ftype))

    def _find_yaml_config_files(self):
        """ Load YAML Config Files in order, check merge flags, keep origin of settings"""
        pass

    def get_plugin_options(self, plugin_type, name, keys=None, variables=None, direct=None):
        options, dummy = self.get_plugin_options_and_origins(plugin_type, name, keys=keys, variables=variables, direct=direct)
        return options

View on GitHub (pinned to 9cf16a4aca)

Solutions

1. Convert the file to UTF-8: iconv -f latin1 -t utf-8 ansible.cfg -o ansible.cfg.fixed (choose the real source encoding)
2. Re-save the file as UTF-8 without BOM from your editor
3. Detect the encoding first if unknown: file -bi ansible.cfg

Example fix

# before
$ ansible --version  # ansible.cfg saved as UTF-16 by Notepad
ERROR! Error reading config file(ansible.cfg) because the config file was not utf8 encoded...

# after
$ iconv -f UTF-16 -t UTF-8 ansible.cfg > ansible.cfg.utf8 && mv ansible.cfg.utf8 ansible.cfg
$ ansible --version

def config_is_utf8(path: str) -> bool:
    try:
        with open(path, 'rb') as f:
            f.read().decode('utf-8')
        return True
    except UnicodeDecodeError:
        return False

assert config_is_utf8('ansible.cfg'), 'convert ansible.cfg to UTF-8 (watch for UTF-16/BOM from Windows editors)'

When it happens

Trigger: An ansible.cfg (or file passed via ANSIBLE_CONFIG) saved in Latin-1/UTF-16/Windows-1252 — often by editors on Windows (Notepad defaults), or files with a UTF-16 BOM — then running any ansible command that loads configuration.

Common situations: Configs edited on Windows machines, templates copied from Word/confluence introducing smart quotes in another encoding, SSH sessions pasting non-UTF-8 bytes, or CI templates rendered with the wrong charset.

Related errors

• Error reading config file (%s): %s
• Failed to logon {0}
• The value '{0}' is not a valid boolean. Valid booleans inclu
• {0} cannot be converted to a list
• Unsupported configuration file extension for %s: %s

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