{"record":{"id":"7c08cba92fddcc25","repo":"infiniflow/ragflow","slug":"invalid-config-file-local-path","errorCode":null,"errorMessage":"Invalid config file: \"{local_path}\".","messagePattern":"Invalid config file: \"(.+?)\"\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"common/config_utils.py","lineNumber":63,"sourceCode":"            yaml.dump(config, f)\n    except Exception as e:\n        raise EnvironmentError(\"rewrite yaml file config {} failed:\".format(conf_path), e)\n\n\ndef conf_realpath(conf_name):\n    conf_path = f\"conf/{conf_name}\"\n    return os.path.join(get_project_base_directory(), conf_path)\n\n\ndef read_config(conf_name=SERVICE_CONF):\n    local_config = {}\n    local_path = conf_realpath(f\"local.{conf_name}\")\n\n    # load local config file\n    if os.path.exists(local_path):\n        local_config = load_yaml_conf(local_path)\n        if not isinstance(local_config, dict):\n            raise ValueError(f'Invalid config file: \"{local_path}\".')\n\n    global_config_path = conf_realpath(conf_name)\n    global_config = load_yaml_conf(global_config_path)\n\n    if not isinstance(global_config, dict):\n        raise ValueError(f'Invalid config file: \"{global_config_path}\".')\n\n    global_config.update(local_config)\n    return global_config\n\n\nCONFIGS = read_config()\n\n\ndef show_configs():\n    msg = f\"Current configs, from {conf_realpath(SERVICE_CONF)}:\"\n    for k, v in CONFIGS.items():\n        if isinstance(v, dict):","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/config_utils.py#L45-L81","documentation":"ValueError raised by read_config in common/config_utils.py:60-63. At import time RAGFlow loads conf/local.<service>.yaml (the local override of service_conf.yaml); if the file parses to something other than a mapping — e.g. the YAML root is a list or a scalar — the loader rejects it. This fires before the global config is even read, so the whole module import / process startup fails.","triggerScenarios":"Creating conf/local.service_conf.yaml whose top-level YAML structure is a list ('- key: value') or a bare scalar instead of a mapping of key: value pairs. Happens at CONFIGS = read_config() module import time, so any entrypoint importing common.config_utils dies immediately.","commonSituations":"Hand-editing the local override and accidentally prefixing lines with '- '; pasting an example snippet that is a YAML list; truncating the file so YAML parses as a scalar; copy-pasting a docker-compose fragment into the wrong file.","solutions":["Open conf/local.service_conf.yaml and make the root node a mapping: every top-level line must be 'key:' or 'key: value', no leading dashes.","Validate the file with a YAML linter (e.g. 'python -c \"import yaml;print(type(yaml.safe_load(open('conf/local.service_conf.yaml'))))\") and confirm it prints <class 'dict'>.","If the file was created by mistake, delete or rename it — read_config skips a missing local file cleanly."],"exampleFix":"# before: conf/local.service_conf.yaml\n- mysql:\n    host: db\n# after\nmysql:\n  host: db","handlingStrategy":"validation","validationCode":"import yaml\nwith open(\"conf/local.service_conf.yaml\") as f:\n    data = yaml.safe_load(f)\nassert isinstance(data, dict) or data is None, \"local override must be a YAML mapping\"","typeGuard":"def is_valid_local_conf(path: str) -> bool:\n    import yaml, os\n    if not os.path.exists(path):\n        return True\n    with open(path) as f:\n        return isinstance(yaml.safe_load(f), dict)","tryCatchPattern":"try:\n    from common.config_utils import CONFIGS\nexcept ValueError as e:\n    if \"Invalid config file\" in str(e):\n        # parse e to get the path, fix the file, then restart\n        ...\n    raise","preventionTips":["Lint YAML overrides in CI (yaml.safe_load + isinstance dict check).","Never prefix top-level config keys with '- '.","Prefer deleting an unneeded local override to leaving a malformed one."],"tags":["config","yaml","startup","local-config"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}