{"record":{"id":"2ae1eea235106d11","repo":"ansible/ansible","slug":"error-reading-config-file-s-because-the-config-f","errorCode":null,"errorMessage":"Error reading config file(%s) because the config file was not utf8 encoded: %s","messagePattern":"Error reading config file\\((.+?)\\) because the config file was not utf8 encoded: (.+?)","errorType":"exception","errorClass":"AnsibleOptionsError","httpStatus":null,"severity":"error","filePath":"lib/ansible/config/manager.py","lineNumber":437,"sourceCode":"        raise AnsibleError(\n            \"Missing base YAML definition file (bad install?): %s\" % to_native(yml_file))\n\n    def _parse_config_file(self, cfile=None):\n        \"\"\" return flat configuration settings from file(s) \"\"\"\n        # TODO: take list of files with merge/nomerge\n\n        if cfile is None:\n            cfile = self._config_file\n\n        ftype = get_config_type(cfile)\n        if cfile is not None:\n            if ftype == 'ini':\n                self._parsers[cfile] = configparser.ConfigParser(inline_comment_prefixes=(';',))\n                with open(to_bytes(cfile), 'rb') as f:\n                    try:\n                        cfg_text = to_text(f.read(), errors='surrogate_or_strict')\n                    except UnicodeError as e:\n                        raise AnsibleOptionsError(\"Error reading config file(%s) because the config file was not utf8 encoded: %s\" % (cfile, to_native(e)))\n                try:\n                    self._parsers[cfile].read_string(cfg_text)\n                except configparser.Error as e:\n                    raise AnsibleOptionsError(\"Error reading config file (%s): %s\" % (cfile, to_native(e)))\n            # FIXME: this should eventually handle yaml config files\n            # elif ftype == 'yaml':\n            #     with open(cfile, 'rb') as config_stream:\n            #         self._parsers[cfile] = yaml_load(config_stream)\n            else:\n                raise AnsibleOptionsError(\"Unsupported configuration file type: %s\" % to_native(ftype))\n\n    def _find_yaml_config_files(self):\n        \"\"\" Load YAML Config Files in order, check merge flags, keep origin of settings\"\"\"\n        pass\n\n    def get_plugin_options(self, plugin_type, name, keys=None, variables=None, direct=None):\n        options, dummy = self.get_plugin_options_and_origins(plugin_type, name, keys=keys, variables=variables, direct=direct)\n        return options","sourceCodeStart":419,"sourceCodeEnd":455,"githubUrl":"https://github.com/ansible/ansible/blob/9cf16a4aca7898481c257f1e17ad28d0b67b1f85/lib/ansible/config/manager.py#L419-L455","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Convert the file to UTF-8: iconv -f latin1 -t utf-8 ansible.cfg -o ansible.cfg.fixed (choose the real source encoding)","Re-save the file as UTF-8 without BOM from your editor","Detect the encoding first if unknown: file -bi ansible.cfg"],"exampleFix":"# before\n$ ansible --version  # ansible.cfg saved as UTF-16 by Notepad\nERROR! Error reading config file(ansible.cfg) because the config file was not utf8 encoded...\n\n# after\n$ iconv -f UTF-16 -t UTF-8 ansible.cfg > ansible.cfg.utf8 && mv ansible.cfg.utf8 ansible.cfg\n$ ansible --version","handlingStrategy":"validation","validationCode":"def config_is_utf8(path: str) -> bool:\n    try:\n        with open(path, 'rb') as f:\n            f.read().decode('utf-8')\n        return True\n    except UnicodeDecodeError:\n        return False\n\nassert config_is_utf8('ansible.cfg'), 'convert ansible.cfg to UTF-8 (watch for UTF-16/BOM from Windows editors)'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Save config files as UTF-8 without BOM","Add an editorconfig/.gitattributes (* text=auto eol=lf) so Windows checkouts stay UTF-8"],"tags":["ansible","configuration","encoding","utf8","ini"],"backgroundTag":null,"analyzedSha":"9cf16a4aca7898481c257f1e17ad28d0b67b1f85","analyzedAt":"2026-08-15T00:15:47.100Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}