oraios/serena · error · ValueError

Project '{project_root_or_name}' is not registered with Sere

Error message

Project '{project_root_or_name}' is not registered with Serena.

What it means

Raised by ProjectServer._get_project when the requested project name or root path is not present in Serena's registry of known projects. Serena only operates on projects that have been registered in its configuration, so any query against an unknown project fails fast with this ValueError instead of silently auto-registering.

Source

Thrown at src/serena/project_server.py:92

        self._setup_routes()

    def _setup_routes(self) -> None:
        @self._app.route("/heartbeat", methods=["GET"])
        def heartbeat() -> dict[str, str]:
            return {"status": "alive"}

        @self._app.route("/query_project", methods=["POST"])
        def query_project() -> str:
            query_request = QueryProjectRequest.model_validate(request.get_json())
            return self._query_project(query_request)

    def _get_project(self, project_root_or_name: str) -> "Project":
        """Gets the project with the given name, loading it if necessary."""
        serena_config = self._agent.serena_config
        registered_project = serena_config.get_registered_project(project_root_or_name)
        if registered_project is None:
            raise ValueError(f"Project '{project_root_or_name}' is not registered with Serena.")

        key = str(registered_project.project_root)

        # find or publish the per-project load lock while holding the shared dictionaries
        with self._loaded_projects_lock:
            project = self._loaded_projects_by_root.get(key)
            if project is not None:
                return project
            project_load_lock = self._project_load_locks_by_root.get(key)
            if project_load_lock is None:
                project_load_lock = threading.Lock()
                self._project_load_locks_by_root[key] = project_load_lock

        # initialize only this project; another project's cached lookup or cold load can proceed
        with project_load_lock:
            with self._loaded_projects_lock:
                project = self._loaded_projects_by_root.get(key)
                if project is not None:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Register the project with Serena (e.g. serena_config.register_project on the project root) before querying it
Check the exact registered name/root via the project list in Serena config and use that string verbatim
If the repo moved, re-register or update the stored project_root in the Serena configuration

Example fix

// before
server.query_project("my-repo/", "find_symbol", "{}")  # unregistered root string
// after
serena_config.register_project(Project("/path/to/my-repo"))
server.query_project("my-repo", "find_symbol", "{}")

Defensive patterns

Strategy: validation

Validate before calling

registered = serena_config.get_registered_project(name)
if registered is None:
    serena_config.register_project(Project(root))  # or surface a clear config error

Type guard

def is_registered(name: str, cfg) -> bool:
    return cfg.get_registered_project(name) is not None

Try / catch

try:
    result = server.query_project(name, tool, params)
except ValueError as e:
    if "not registered with Serena" in str(e):
        register_and_retry(name)
    else:
        raise

Prevention

Register all projects in the Serena config before starting the server
Use exact registered names/roots, avoiding trailing slashes and symlinked paths
In CI, assert project registration as a startup step

When it happens

Trigger: Calling query_project (or any route that ends in _get_project) with a project_name that was never registered via serena_config.register_project or the projects YAML config; typos in project name; passing a root path whose trailing slash or symlink differs from the registered root.

Common situations: Developers point a client at a Serena ProjectServer before registering the repository; CI environments where the .serena/projects config was not copied; renamed or moved repositories that invalidate the stored project root path.

Related errors

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