oraios/serena · error · ValueError

No active project. Please activate a project first.

Error message

No active project. Please activate a project first.

What it means

get_active_project_or_raise() is the strict accessor for the agent's currently active project; it raises ValueError when no project has been activated yet. Serena requires an active project for most symbol-level tools (find_symbol, references, etc.). It exists so callers get a clear, actionable message instead of an AttributeError on None.

Source

Thrown at src/serena/agent.py:928

            of tools that can be offered during the session.
            If a client should attempt to use a tool that is dynamically disabled
            (e.g. because a project is activated that disables it), it will receive an error.
        """
        return list(self._exposed_tools.tools)

    def get_active_project(self) -> Project | None:
        """
        :return: the active project or None if no project is active
        """
        return self._active_project

    def get_active_project_or_raise(self) -> Project:
        """
        :return: the active project or raises an exception if no project is active
        """
        project = self.get_active_project()
        if project is None:
            raise ValueError("No active project. Please activate a project first.")
        return project

    def get_active_modes(self) -> ActiveModes:
        """
        :return: the active modes
        """
        return self._active_modes

    @staticmethod
    def _create_prompt_tool_names_mapping(language_backend: LanguageBackend) -> dict[str, str]:
        """
        Creates a mapping from tool names to new tool names, which take into consideration

           * legacy tool names, where the name was changed and
           * LSP tools which are functionally replaced by other tools due to the active language backend
             (e.g. "find_symbol" being replaced by "jet_brains_find_symbol" in JetBrains mode).

        The mapping is intended to be used for the generation of prompts, such that prompts can

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Activate a project first: use the activate_project tool with a registered project name or an absolute directory path.
2. Start Serena with --project /path/to/project (or --project <registered-name>) so a project is active from startup.
3. Register the project in serena_config.yml if its name was typo'd; check the 'Existing project names' list surfaced in related errors.
4. In code, call agent.get_active_project() and handle None before invoking project-dependent tools.

Example fix

// before
symbol = agent.project().find_symbol('foo')
// after
if agent.get_active_project() is None:
    agent.activate_project_from_path_or_name('/path/to/project')
symbol = agent.project().find_symbol('foo')

def ensure_active_project(agent) -> bool:
    return agent.get_active_project() is not None

def get_project_or_none(agent):
    p = agent.get_active_project()
    return p if isinstance(p, Project) else None

try:
    project = agent.get_active_project_or_raise()
except ValueError as e:
    agent.activate_project_from_path_or_name('/path/to/project')
    project = agent.get_active_project_or_raise()

When it happens

Trigger: Calling any tool/method that routes through get_active_project_or_raise (project, get_language_server_manager_or_raise, add/remove_language_server, _referencing_symbol_names, symbol tools) before activate_project / --project startup activation succeeded.

Common situations: Starting the MCP server without the --project flag and calling symbol tools first; a failed earlier activation (bad project name/path or backend mismatch) leaving no active project; calling add_language_server or reset_language_server_manager in a fresh session.

Related errors

• Cannot activate project '{project.project_name}': it require
• Project '{project_root_or_name}' not found: Not a valid proj
• e.get_error_message()
• Invalid tool name: {tool_name}{caller_context_for_logging}

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