oraios/serena · error · ValueError

Cannot activate project '{project.project_name}': it require

Error message

Cannot activate project '{project.project_name}': it requires the {project_backend.value} backend, but this session was initialized with {self._language_backend.value}. Workarounds: (1) Use project activation at startup via the --project flag, (2) Configure one MCP server per backend in your client.

What it means

_activate_project rejects projects whose serena.yml declares a language_backend (e.g. solid-lsp vs multilsp) that differs from the backend the current session was initialized with. Because the language server backend is fixed at process start, mid-session activation of a mismatched project would break symbol tooling, so Serena raises ValueError with two documented workarounds.

Source

Thrown at src/serena/agent.py:1226

        """
        return self._language_backend == LanguageBackend.LSP

    def _activate_project(self, project: Project, update_active_modes: bool = True, update_active_tools: bool = True) -> bool:
        """
        :return: True if the project was newly activated, False if it was already active
        """
        # check if the project is already active
        if self._active_project is not None and self._active_project.project_root == project.project_root:
            return False

        log.info(f"Activating {project.project_name} at {project.project_root}")

        self._project_activation_error = None

        # check if the project requires a different language backend than the one initialized at startup
        project_backend = project.project_config.language_backend
        if project_backend is not None and project_backend != self._language_backend:
            raise ValueError(
                f"Cannot activate project '{project.project_name}': it requires the {project_backend.value} backend, "
                f"but this session was initialized with {self._language_backend.value}. "
                f"Workarounds: (1) Use project activation at startup via the --project flag, "
                f"(2) Configure one MCP server per backend in your client."
            )

        # shut down the previously active project to release its language server processes
        if self._active_project is not None:
            log.info(f"Shutting down previously active project '{self._active_project.project_name}' before switching")
            self._active_project.shutdown()

        self._active_project = project
        project.set_agent(self)

        if update_active_modes:
            active_mode_names_before = set(self._active_modes.get_mode_names())
            self._update_active_modes()
            newly_activated_mode_names = set(self._active_modes.get_mode_names()) - active_mode_names_before

View on GitHub (pinned to 7fcbca7e62)

Solutions

Restart Serena with --project pointing at the target project so the session is initialized with the project's backend.
Configure one MCP server per backend in your MCP client (e.g. serena-backend-a, serena-backend-b) and connect to the matching one.
Change the project's language_backend in its .serena/project.yml to match the session backend, if the project supports it.

Example fix

// before (client calls one shared server)
agent.activate_project_from_path_or_name('other-project')
// after: start server scoped to the project
// serena start-mcp-server --project /path/to/other-project
// then activate is consistent with session backend

Defensive patterns

Strategy: validation

Validate before calling

def backend_compatible(agent, project) -> bool:
    pb = project.project_config.language_backend
    return pb is None or pb == agent._language_backend

Type guard

def is_compatible_project(project, session_backend) -> bool:
    pb = getattr(getattr(project, 'project_config', None), 'language_backend', None)
    return pb is None or pb == session_backend

Try / catch

try:
    agent.activate_project_from_path_or_name(path)
except ValueError as e:
    if 'backend' in str(e):
        log.error('Restart serena with --project %s (backend mismatch)', path)
    raise

Prevention

Run one Serena MCP server per language backend in your client configuration.
Pin the project at startup with --project instead of switching projects mid-session across backends.
Keep language_backend consistent across your projects' .serena/project.yml files when sharing one server.

When it happens

Trigger: Calling activate_project_from_path_or_name (or the activate_project tool) for a project whose project_config.language_backend is set and != self._language_backend of the running agent.

Common situations: One Serena MCP server instance shared across projects configured with different backends; a project.yml edited to pin a new backend after the session started; switching between single-language (solid-lsp) and multi-language server projects in one client session.

Related errors

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