{"record":{"id":"9e2d429bb9037702","repo":"oraios/serena","slug":"project-project-root-or-name-is-not-registered","errorCode":null,"errorMessage":"Project '{project_root_or_name}' is not registered with Serena.","messagePattern":"Project '(.+?)' is not registered with Serena\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/serena/project_server.py","lineNumber":92,"sourceCode":"\n        self._setup_routes()\n\n    def _setup_routes(self) -> None:\n        @self._app.route(\"/heartbeat\", methods=[\"GET\"])\n        def heartbeat() -> dict[str, str]:\n            return {\"status\": \"alive\"}\n\n        @self._app.route(\"/query_project\", methods=[\"POST\"])\n        def query_project() -> str:\n            query_request = QueryProjectRequest.model_validate(request.get_json())\n            return self._query_project(query_request)\n\n    def _get_project(self, project_root_or_name: str) -> \"Project\":\n        \"\"\"Gets the project with the given name, loading it if necessary.\"\"\"\n        serena_config = self._agent.serena_config\n        registered_project = serena_config.get_registered_project(project_root_or_name)\n        if registered_project is None:\n            raise ValueError(f\"Project '{project_root_or_name}' is not registered with Serena.\")\n\n        key = str(registered_project.project_root)\n\n        # find or publish the per-project load lock while holding the shared dictionaries\n        with self._loaded_projects_lock:\n            project = self._loaded_projects_by_root.get(key)\n            if project is not None:\n                return project\n            project_load_lock = self._project_load_locks_by_root.get(key)\n            if project_load_lock is None:\n                project_load_lock = threading.Lock()\n                self._project_load_locks_by_root[key] = project_load_lock\n\n        # initialize only this project; another project's cached lookup or cold load can proceed\n        with project_load_lock:\n            with self._loaded_projects_lock:\n                project = self._loaded_projects_by_root.get(key)\n                if project is not None:","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/project_server.py#L74-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nserver.query_project(\"my-repo/\", \"find_symbol\", \"{}\")  # unregistered root string\n// after\nserena_config.register_project(Project(\"/path/to/my-repo\"))\nserver.query_project(\"my-repo\", \"find_symbol\", \"{}\")","handlingStrategy":"validation","validationCode":"registered = serena_config.get_registered_project(name)\nif registered is None:\n    serena_config.register_project(Project(root))  # or surface a clear config error","typeGuard":"def is_registered(name: str, cfg) -> bool:\n    return cfg.get_registered_project(name) is not None","tryCatchPattern":"try:\n    result = server.query_project(name, tool, params)\nexcept ValueError as e:\n    if \"not registered with Serena\" in str(e):\n        register_and_retry(name)\n    else:\n        raise","preventionTips":["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"],"tags":["serena","configuration","project-registration"],"backgroundTag":"project-not-registered","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}