{"record":{"id":"2d16acf502c8151e","repo":"Aider-AI/aider","slug":"error-loading-model-settings-from-model-settings","errorCode":null,"errorMessage":"Error loading model settings from {model_settings_fname}: {e}","messagePattern":"Error loading model settings from (.+?): (.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"aider/models.py","lineNumber":1106,"sourceCode":"        if not os.path.exists(model_settings_fname):\n            continue\n\n        if not Path(model_settings_fname).read_text().strip():\n            continue\n\n        try:\n            with open(model_settings_fname, \"r\") as model_settings_file:\n                model_settings_list = yaml.safe_load(model_settings_file)\n\n            for model_settings_dict in model_settings_list:\n                model_settings = ModelSettings(**model_settings_dict)\n\n                # Remove all existing settings for this model name\n                MODEL_SETTINGS[:] = [ms for ms in MODEL_SETTINGS if ms.name != model_settings.name]\n                # Add the new settings\n                MODEL_SETTINGS.append(model_settings)\n        except Exception as e:\n            raise Exception(f\"Error loading model settings from {model_settings_fname}: {e}\")\n        files_loaded.append(model_settings_fname)\n\n    return files_loaded\n\n\ndef register_litellm_models(model_fnames):\n    files_loaded = []\n    for model_fname in model_fnames:\n        if not os.path.exists(model_fname):\n            continue\n\n        try:\n            data = Path(model_fname).read_text()\n            if not data.strip():\n                continue\n            model_def = json5.loads(data)\n            if not model_def:\n                continue","sourceCodeStart":1088,"sourceCodeEnd":1124,"githubUrl":"https://github.com/Aider-AI/aider/blob/5dc9490bb35f9729ef2c95d00a19ccd30c26339c/aider/models.py#L1088-L1124","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Read the wrapped ': {e}' portion — for YAML errors it includes line/column; fix the syntax at that location in the named file.","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.","Check the file is a top-level YAML list of mappings, one entry per model, each with 'name' plus valid fields.","Lint the file first: python -c \"import yaml,sys; yaml.safe_load(open('FILE'))\" to isolate pure YAML errors from schema errors."],"exampleFix":"# before (invalid: unknown key, bad indent)\n- name: my/model\n   usecache: true   # typo + indent error\n\n# after\n- name: my/model\n  use_cache: true","handlingStrategy":"validation","validationCode":"import yaml\nfrom dataclasses import fields\nfrom aider.models import ModelSettings\n\ndef validate_model_settings_file(path):\n    data = yaml.safe_load(open(path))  # raises here first if YAML is broken\n    assert isinstance(data, list), \"top level must be a YAML list\"\n    valid = {f.name for f in fields(ModelSettings)}\n    for i, entry in enumerate(data):\n        unknown = set(entry) - valid\n        if unknown:\n            raise ValueError(f\"entry {i}: unknown keys {sorted(unknown)}; valid={sorted(valid)}\")\n    return True","typeGuard":null,"tryCatchPattern":"try:\n    files = load_model_settings([path])\nexcept Exception as e:\n    if \"Error loading model settings\" in str(e):\n        print(f\"Fix {path}: underlying error is after the colon: {e}\")\n    raise","preventionTips":["Lint the YAML standalone before wiring it in: python -c \"import yaml; yaml.safe_load(open('f.yml'))\".","Derive allowed keys from ModelSettings fields of your installed version instead of copying examples from other versions.","Keep each model entry minimal — only fields you actually override — to reduce schema-mismatch surface."],"tags":["yaml","configuration","model-settings","parsing","aider"],"backgroundTag":null,"analyzedSha":"5dc9490bb35f9729ef2c95d00a19ccd30c26339c","analyzedAt":"2026-08-15T05:40:10.498Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}