infiniflow/ragflow · critical · ValueError

Invalid config file: "{local_path}".

Error message

Invalid config file: "{local_path}".

What it means

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.

Source

Thrown at common/config_utils.py:63

            yaml.dump(config, f)
    except Exception as e:
        raise EnvironmentError("rewrite yaml file config {} failed:".format(conf_path), e)


def conf_realpath(conf_name):
    conf_path = f"conf/{conf_name}"
    return os.path.join(get_project_base_directory(), conf_path)


def read_config(conf_name=SERVICE_CONF):
    local_config = {}
    local_path = conf_realpath(f"local.{conf_name}")

    # load local config file
    if os.path.exists(local_path):
        local_config = load_yaml_conf(local_path)
        if not isinstance(local_config, dict):
            raise ValueError(f'Invalid config file: "{local_path}".')

    global_config_path = conf_realpath(conf_name)
    global_config = load_yaml_conf(global_config_path)

    if not isinstance(global_config, dict):
        raise ValueError(f'Invalid config file: "{global_config_path}".')

    global_config.update(local_config)
    return global_config


CONFIGS = read_config()


def show_configs():
    msg = f"Current configs, from {conf_realpath(SERVICE_CONF)}:"
    for k, v in CONFIGS.items():
        if isinstance(v, dict):

View on GitHub (pinned to 554fb1133a)

Solutions

1. 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.
2. 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'>.
3. If the file was created by mistake, delete or rename it — read_config skips a missing local file cleanly.

Example fix

# before: conf/local.service_conf.yaml
- mysql:
    host: db
# after
mysql:
  host: db

import yaml
with open("conf/local.service_conf.yaml") as f:
    data = yaml.safe_load(f)
assert isinstance(data, dict) or data is None, "local override must be a YAML mapping"

def is_valid_local_conf(path: str) -> bool:
    import yaml, os
    if not os.path.exists(path):
        return True
    with open(path) as f:
        return isinstance(yaml.safe_load(f), dict)

try:
    from common.config_utils import CONFIGS
except ValueError as e:
    if "Invalid config file" in str(e):
        # parse e to get the path, fix the file, then restart
        ...
    raise

When it happens

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

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

Related errors

• Invalid config file: "{global_config_path}".
• rewrite yaml file config {} failed:
• No private key
• Can't init admin.
• Invalid Tenki provider configuration.

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/7c08cba92fddcc25. Report an issue: GitHub.