{"record":{"id":"57c08ea1030bc7ed","repo":"infiniflow/ragflow","slug":"invalid-config-file-global-config-path","errorCode":null,"errorMessage":"Invalid config file: \"{global_config_path}\".","messagePattern":"Invalid config file: \"(.+?)\"\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"common/config_utils.py","lineNumber":69,"sourceCode":"    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):\n            if \"password\" in v:\n                v = copy.deepcopy(v)\n                v[\"password\"] = \"*\" * 8\n            if \"access_key\" in v:\n                v = copy.deepcopy(v)\n                v[\"access_key\"] = \"*\" * 8","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/common/config_utils.py#L51-L87","documentation":"ValueError raised by read_config in common/config_utils.py:66-69. The main configuration file conf/service_conf.yaml must be a YAML mapping at its root; if it parses to a list, scalar, or null (empty file parses to None, which is not a dict), startup aborts. Because CONFIGS = read_config() executes at import time of common.config_utils, every service entrypoint (API server, task executor) crashes on import when this fires.","triggerScenarios":"Editing conf/service_conf.yaml so its root is not a mapping: top-level list items, a file containing only comments (parses to None), or a mangled/truncated file. Any process that imports common.config_utils then fails during startup.","commonSituations":"Bad merge or rebase leaving stray '- ' prefixes; template substitution leaving the file empty; hand-editing under time pressure and breaking indentation so the document root becomes a list; mounting an empty file over conf/service_conf.yaml in docker.","solutions":["Fix conf/service_conf.yaml so the top level is key: value pairs only (no leading dashes, file not empty).","Verify with: python -c \"import yaml;d=yaml.safe_load(open('conf/service_conf.yaml'));print(type(d))\" — must be <class 'dict'>.","If the file is empty, restore it from git (git checkout -- conf/service_conf.yaml) and reapply your changes."],"exampleFix":"# before: empty or list-rooted service_conf.yaml\n- es:\n    hosts: es01:9200\n# after\nes:\n  hosts: es01:9200","handlingStrategy":"validation","validationCode":"import yaml\nwith open(\"conf/service_conf.yaml\") as f:\n    data = yaml.safe_load(f)\nassert isinstance(data, dict), \"service_conf.yaml root must be a mapping\"","typeGuard":"def is_valid_service_conf(path: str) -> bool:\n    import yaml\n    with open(path) as f:\n        return isinstance(yaml.safe_load(f), dict)","tryCatchPattern":"try:\n    import common.config_utils\nexcept ValueError as e:\n    if \"Invalid config file\" in str(e):\n        path = str(e).split('\"')[1]  # extract offending path from the message\n        restore_or_fix(path)\n    raise","preventionTips":["Add a startup preflight script validating all conf/*.yaml roots are dicts.","Never commit an empty or list-rooted service_conf.yaml.","Mount config files (not empty placeholders) in docker deployments."],"tags":["config","yaml","startup","service-conf"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}