oraios/serena · error · SerenaConfigError

`projects` key not found in Serena configuration. Please upd

Error message

`projects` key not found in Serena configuration. Please update your `serena_config.yml` file.

What it means

After parsing serena_config.yml, from_config_file() requires the top-level `projects` key listing registered project paths. Older or hand-trimmed config files lacking this key are rejected with SerenaConfigError, telling the user to update their config to the new schema.

Source

Thrown at src/serena/config/serena_config.py:1064

        # create the configuration instance
        instance = cls(_loaded_commented_yaml=loaded_commented_yaml, _config_file_path=config_file_path)
        num_migrations = 0

        def get_value_or_default(field_name: str) -> Any:
            nonlocal num_migrations
            if field_name not in loaded_commented_yaml:
                num_migrations += 1
            return loaded_commented_yaml.get(field_name, get_dataclass_default(SerenaConfig, field_name))

        # transfer regular fields that do not require type conversion
        for field_name in instance._iter_config_file_mapped_fields_without_type_conversion():
            assert hasattr(instance, field_name)
            setattr(instance, field_name, get_value_or_default(field_name))

        # read projects
        if "projects" not in loaded_commented_yaml:
            raise SerenaConfigError("`projects` key not found in Serena configuration. Please update your `serena_config.yml` file.")
        instance.projects = []
        for path in loaded_commented_yaml["projects"] or []:
            path = Path(path).resolve()
            try:
                path_exists = path.exists()
            except OSError as e:
                log.warning(f"Project path {path} is not accessible ({e}), skipping.")
                continue
            if not path_exists or (path.is_dir() and not os.path.isfile(instance.get_project_yml_location(str(path)))):
                log.warning(f"Project path {path} does not exist or no associated project configuration file found, skipping.")
                continue
            if path.is_file():
                path = cls._migrate_out_of_project_config_file(path)
                if path is None:
                    continue
                num_migrations += 1
            try:
                project_config = ProjectConfig.load(path, serena_config=instance)  # instance is sufficiently populated

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Add a `projects:` key to serena_config.yml (an empty list `projects: []` is valid) and re-run.
2. Regenerate the config from the current template (delete the old file and let from_config_file(generate_if_missing=True) recreate it), then re-add your settings.
3. If migrating, run Serena's config migration path (from_config_file performs migrations) rather than hand-building the file.

Example fix

// before (serena_config.yml)
gui_launch_window: 0
// after
projects: []
gui_launch_window: 0

import yaml
data = yaml.safe_load(open(config_path))
if 'projects' not in data:
    data['projects'] = []  # or rewrite the file with the key added

def has_projects_key(path) -> bool:
    import yaml
    return 'projects' in (yaml.safe_load(open(path)) or {})

try:
    config = SerenaConfig.from_config_file()
except SerenaConfigError as e:
    if 'projects' in str(e):
        add_projects_key_to_yml(); config = SerenaConfig.from_config_file()
    else:
        raise

When it happens

Trigger: Loading a serena_config.yml (generated by an older Serena version or edited to remove the key) that has no `projects` mapping/sequence; from_config_file then raises during startup of make_agent, main, edit, etc.

Common situations: Upgrading Serena from a version whose config template had no `projects` key; copying only partial settings into a fresh config; manually pruning the file and deleting the empty-looking `projects:` section.

Related errors

• Context file not found: {path.resolve()}
• Cannot use both fixed_tools and excluded_tools/included_opti
• Unknown language backend '{backend_str}': valid values are {
• Invalid line_ending: {value!r}. Valid values are: {valid}
• Cannot use interactive mode with asynchronous auto-generatio

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/1fc8ef8071734038. Report an issue: GitHub.