Aider-AI/aider · error · Exception

Error loading model settings from {model_settings_fname}: {e

Error message

Error loading model settings from {model_settings_fname}: {e}

What it means

load_model_settings in aider/models.py parses a YAML file of model settings lists; any failure while opening, yaml.safe_load-ing, or unpacking each dict into ModelSettings(**dict) is caught and re-raised as a bare Exception wrapping the original message plus the file path. Common originals: YAML syntax errors, a mapping key not a ModelSettings field (unexpected TypeError kwarg), a missing required field, or a non-list YAML document iterated incorrectly.

Source

Thrown at aider/models.py:1106

        if not os.path.exists(model_settings_fname):
            continue

        if not Path(model_settings_fname).read_text().strip():
            continue

        try:
            with open(model_settings_fname, "r") as model_settings_file:
                model_settings_list = yaml.safe_load(model_settings_file)

            for model_settings_dict in model_settings_list:
                model_settings = ModelSettings(**model_settings_dict)

                # Remove all existing settings for this model name
                MODEL_SETTINGS[:] = [ms for ms in MODEL_SETTINGS if ms.name != model_settings.name]
                # Add the new settings
                MODEL_SETTINGS.append(model_settings)
        except Exception as e:
            raise Exception(f"Error loading model settings from {model_settings_fname}: {e}")
        files_loaded.append(model_settings_fname)

    return files_loaded


def register_litellm_models(model_fnames):
    files_loaded = []
    for model_fname in model_fnames:
        if not os.path.exists(model_fname):
            continue

        try:
            data = Path(model_fname).read_text()
            if not data.strip():
                continue
            model_def = json5.loads(data)
            if not model_def:
                continue

View on GitHub (pinned to 5dc9490bb3)

Solutions

1. Read the wrapped ': {e}' portion — for YAML errors it includes line/column; fix the syntax at that location in the named file.
2. Validate against the ModelSettings schema of your installed version (inspect its dataclass fields in aider/models.py) and remove/rename unknown or typo'd keys.
3. Check the file is a top-level YAML list of mappings, one entry per model, each with 'name' plus valid fields.
4. Lint the file first: python -c "import yaml,sys; yaml.safe_load(open('FILE'))" to isolate pure YAML errors from schema errors.

Example fix

# before (invalid: unknown key, bad indent)
- name: my/model
   usecache: true   # typo + indent error

# after
- name: my/model
  use_cache: true

import yaml
from dataclasses import fields
from aider.models import ModelSettings

def validate_model_settings_file(path):
    data = yaml.safe_load(open(path))  # raises here first if YAML is broken
    assert isinstance(data, list), "top level must be a YAML list"
    valid = {f.name for f in fields(ModelSettings)}
    for i, entry in enumerate(data):
        unknown = set(entry) - valid
        if unknown:
            raise ValueError(f"entry {i}: unknown keys {sorted(unknown)}; valid={sorted(valid)}")
    return True

try:
    files = load_model_settings([path])
except Exception as e:
    if "Error loading model settings" in str(e):
        print(f"Fix {path}: underlying error is after the colon: {e}")
    raise

When it happens

Trigger: Pointing aider at a --model-settings-file whose YAML has tabs/indentation errors, a top-level scalar instead of a list of dicts, a typo'd key like 'extra_param:' (ModelSettings gets an unexpected kwarg), or a wrong type (e.g. use_cache: "yes" where a bool is expected and validation rejects it). The path in the message identifies which file failed.

Common situations: Hand-editing a .aider.model.settings.yml to add a custom model and mis-indenting or inventing field names; copy/pasting YAML from docs of a different aider version whose ModelSettings schema changed (fields renamed/added required).

Related errors

• Error loading model definition from {model_fname}: {e}
• Unknown edit format {edit_format}. Valid formats are: {', '.
• Bad/missing filename. The filename must be alone on the line
• Expected `=======`
• Expected `>>>>>>> REPLACE` or `=======`

AI-assisted analysis of Aider-AI/aider@5dc9490bb3 (2026-08-15). Data as JSON: /api/errors/2d16acf502c8151e. Report an issue: GitHub.