{"record":{"id":"824234ea2dd3efed","repo":"oraios/serena","slug":"projectserver-health-check-failed-e","errorCode":null,"errorMessage":"ProjectServer health check failed: {e}","messagePattern":"ProjectServer health check failed: (.+?)","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"src/serena/project_server.py","lineNumber":175,"sourceCode":"    \"\"\"\n\n    def __init__(self, host: str = \"127.0.0.1\", port: int = ProjectServer.PORT, timeout: int = 300) -> None:\n        \"\"\"\n        :param host: the host address of the project server.\n        :param port: the port of the project server.\n        :raises ConnectionError: if the project server is not reachable.\n        \"\"\"\n        self._base_url = f\"http://{host}:{port}\"\n        self._timeout = timeout\n\n        # verify that the server is running\n        try:\n            response = requests_lib.get(f\"{self._base_url}/heartbeat\", timeout=5)\n            response.raise_for_status()\n        except requests_lib.ConnectionError:\n            raise ConnectionError(f\"ProjectServer is not reachable at {self._base_url}. Make sure the server is running.\")\n        except requests_lib.RequestException as e:\n            raise ConnectionError(f\"ProjectServer health check failed: {e}\")\n\n    def query_project(self, project_name: str, tool_name: str, tool_params_json: str) -> str:\n        \"\"\"\n        Query a project by executing a Serena tool in its context.\n\n        The interface matches :meth:`QueryProjectTool.apply\n        <serena.tools.query_project_tools.QueryProjectTool.apply>`.\n\n        :param project_name: the name of the project to query.\n        :param tool_name: the name of the tool to execute. The tool must be read-only.\n        :param tool_params_json: the parameters to pass to the tool, encoded as a JSON string.\n        :return: the tool's result as a string.\n        \"\"\"\n        payload = QueryProjectRequest(\n            project_name=project_name,\n            tool_name=tool_name,\n            tool_params_json=tool_params_json,\n        ).model_dump()","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/project_server.py#L157-L193","documentation":"Companion to the heartbeat check in ProjectServerClient.__init__: when the server responds but with a non-2xx status (raise_for_status) or another requests error (timeout, TLS, DNS), the constructor raises ConnectionError with the underlying exception message.","triggerScenarios":"Server listening but /heartbeat returning 4xx/5xx (proxy interception, auth layer, misrouted path); request timeout because the server is overloaded; HTTPS base_url against a plain-HTTP server; DNS name not resolving.","commonSituations":"Reverse proxies or corporate proxies returning 403/502 for /heartbeat; using https:// when the server serves http://; transient network flakiness in CI causing timeouts.","solutions":["Read the wrapped exception message for the root cause (status code vs timeout)","Confirm the URL scheme matches the server (http vs https) and that /heartbeat is accessible (curl it)","Increase timeout or retry after checking server logs for errors during startup","Bypass or configure proxies (NO_PROXY) if a corporate proxy is intercepting localhost traffic"],"exampleFix":"// before\nclient = ProjectServerClient(\"https://localhost:24282\")  # server is plain http\n// after\nclient = ProjectServerClient(\"http://localhost:24282\")","handlingStrategy":"retry","validationCode":"r = requests.get(f\"{base_url}/heartbeat\", timeout=5)\nassert r.ok, f\"heartbeat status {r.status_code}\"","typeGuard":null,"tryCatchPattern":"try:\n    client = ProjectServerClient(base_url)\nexcept ConnectionError as e:\n    log.error(\"health check failed: %s\", e)\n    client = retry_with_backoff(lambda: ProjectServerClient(base_url))","preventionTips":["Match URL scheme to the server (http vs https)","Set NO_PROXY for localhost to avoid proxy interception","Check server logs for 5xx causes; increase timeout for slow starts"],"tags":["network","http","health-check"],"backgroundTag":"health-check-failed","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}