oraios/serena · error · FileExistsError

Project file {yml_path} already exists.

Error message

Project file {yml_path} already exists.

What it means

_create_project registers a new project by generating a .serena/project.yml inside the target directory (via SerenaConfig.get_project_yml_location). It raises FileExistsError if a project yml is already present, because re-running creation would overwrite the existing project configuration. This makes project creation idempotent-safe: existing projects must be activated, not recreated.

Source

Thrown at src/serena/cli.py:707

        )

    @staticmethod
    def _create_project(project_path: str, name: str | None, language: tuple[str, ...]) -> RegisteredProject:
        """
        Helper method to create a project configuration file.

        :param project_path: Path to the project directory
        :param name: Optional project name (defaults to directory name if not specified)
        :param language: Tuple of language names
        :raises FileExistsError: If project.yml already exists
        :raises ValueError: If an unsupported language is specified
        :return: the RegisteredProject instance
        """
        project_root = Path(project_path).resolve()
        serena_config = SerenaConfig.from_config_file()
        yml_path = serena_config.get_project_yml_location(str(project_root))
        if os.path.exists(yml_path):
            raise FileExistsError(f"Project file {yml_path} already exists.")

        languages: list[LanguageServerId] = []
        if language:
            for lang in language:
                try:
                    languages.append(LanguageServerId(lang.lower()))
                except ValueError:
                    all_langs = [l.value for l in LanguageServerId]
                    raise ValueError(f"Unknown language '{lang}'. Supported: {all_langs}")

        generated_conf = ProjectConfig.autogenerate(
            project_root=project_path,
            serena_config=serena_config,
            project_name=name,
            languages=languages if languages else None,
            interactive=True,
        )
        languages_str = ", ".join([lang.value for lang in generated_conf.language_servers]) if generated_conf.language_servers else "N/A"

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Skip creation: the project already exists — activate it instead (`serena start-mcp-server --project <path>` or the activate_project tool).
2. If you intend to regenerate, delete or rename the existing project.yml first (after backing up custom settings).
3. In scripts, check os.path.exists(<project>/.serena/project.yml) before calling create, and branch to activate/index logic.
4. Verify you passed the intended project root, not a parent that already contains .serena/project.yml.

Example fix

// before
yml = cfg.get_project_yml_location(str(root))
_create_project(path)  # FileExistsError on re-run
// after
if not os.path.exists(os.path.join(path, '.serena', 'project.yml')):
    _create_project(path)
else:
    agent.activate_project_from_path_or_name(path)

import os
def project_already_created(project_path: str) -> bool:
    root = os.path.abspath(project_path)
    return os.path.exists(os.path.join(root, '.serena', 'project.yml'))

try:
    _create_project(path)
except FileExistsError as e:
    log.info('Project already exists (%s); activating instead', e)
    agent.activate_project_from_path_or_name(path)

When it happens

Trigger: Calling `serena project create <path>` / `serena index` (which auto-creates) or _create_project directly on a directory that already contains a Serena project file (.serena/project.yml at the resolved root).

Common situations: Running `serena index` on an already-registered project; accidentally pointing create at a parent directory that already has a project.yml; re-running setup scripts that call create on every invocation; symlink/resolution making a subdirectory resolve to an existing project root.

Related errors

• {user_prompt_yaml_path} already exists.
• Cannot apply setup for client '{client}' (not found or not f
• Failed to set up Serena for {client}.
• Internal mode '{from_internal}' not found in {SERENAS_OWN_MO
• Internal context '{from_internal}' not found in {SERENAS_OWN

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