oraios/serena · error · ProjectNotFoundError

Project '{project_root_or_name}' not found: Not a valid proj

Error message

Project '{project_root_or_name}' not found: Not a valid project name or directory. Existing project names: {self.serena_config.project_names}

What it means

activate_project_from_path_or_name resolves its argument first as a registered project name, then as a directory path; if neither matches, it raises ProjectNotFoundError listing all registered project names. This guards against typos and paths that don't contain a valid Serena project.

Source

Thrown at src/serena/agent.py:1357

        self, project_root_or_name: str, update_active_modes: bool = True, update_active_tools: bool = True
    ) -> bool:
        """
        Activate a project from a path or a name.
        If the project was already registered, it will just be activated.
        If the argument is a path at which no Serena project previously existed, the project will be created beforehand.
        Raises ProjectNotFoundError if the project could neither be found nor created.

        :return: True if the project was newly activated, False if it was already active
        """
        project_instance: Project | None = self.serena_config.get_project(project_root_or_name)
        if project_instance is not None:
            log.info(f"Found registered project '{project_instance.project_name}' at path {project_instance.project_root}")
        elif os.path.isdir(project_root_or_name):
            project_instance = self.serena_config.add_project_from_path(project_root_or_name, asynchronous_autogen=True)
            log.info(f"Added new project {project_instance.project_name} for path {project_instance.project_root}")

        if project_instance is None:
            raise ProjectNotFoundError(
                f"Project '{project_root_or_name}' not found: Not a valid project name or directory. "
                f"Existing project names: {self.serena_config.project_names}"
            )

        return self._activate_project(project_instance, update_active_modes=update_active_modes, update_active_tools=update_active_tools)

    def get_active_tool_names(self) -> list[str]:
        """
        :return: the list of names of the active tools for the current project, sorted alphabetically
        """
        return self._active_tools.tool_names

    def tool_is_active(self, tool_name: str) -> bool:
        """
        :param tool_class: the name of the tool to check
        :return: True if the tool is active, False otherwise
        """
        return self._active_tools.contains_tool_name(tool_name)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Pass an absolute path to the project root directory (os.path.isdir check must succeed).
Use exactly one of the registered names (check the 'Existing project names' list in the error message or serena_config.yml).
If the project is new, ensure the directory exists and contains (or can autogenerate) .serena/project.yml, then activate by path.
Fix stale registrations pointing at moved directories by re-adding the project with its new path.

Example fix

// before
agent.activate_project_from_path_or_name('myproj')  # name not registered
// after
agent.activate_project_from_path_or_name('/home/user/work/myproj')

Defensive patterns

Strategy: validation

Validate before calling

def can_activate(agent, name_or_path: str) -> bool:
    if os.path.isdir(os.path.abspath(name_or_path)):
        return True
    return name_or_path in agent.serena_config.project_names

Type guard

def is_valid_project_ref(serena_config, ref: str) -> bool:
    return os.path.isdir(ref) or ref in serena_config.project_names

Try / catch

try:
    agent.activate_project_from_path_or_name(ref)
except ProjectNotFoundError:
    log.error('Unknown project %r; registered: %s', ref, agent.serena_config.project_names)
    raise

Prevention

Always pass absolute directory paths (resolve relative paths before calling).
Verify the name against serena_config.project_names or the error's 'Existing project names' list.
Update stale registrations after moving/renaming project directories.
Register new projects (serena project create or add_project_from_path) before activating by name.

When it happens

Trigger: Calling activate_project / activate_project_from_path_or_name with (a) a name not present in serena_config's registered projects and (b) a string that is not an existing directory; also during __init__ when the --project startup flag resolves to nothing.

Common situations: Typos in registered project names; passing a relative path instead of an absolute one; passing a file path instead of a directory; the project directory was moved/renamed after registration; the LLM tool supplying a guessed project name.

Related errors

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