oraios/serena · error · ConnectionError

Failed to connect to Serena service at {url}: {e}

Error message

Failed to connect to Serena service at {url}: {e}

What it means

_make_request wraps requests.exceptions.ConnectionError and re-raises it as a Python ConnectionError with the target URL. This means the Serena service HTTP endpoint inside the JetBrains IDE could not be reached at all (nothing listening, wrong port, IDE busy/blocked).

Source

Thrown at src/serena/jetbrains/jetbrains_plugin_client.py:341

                response = self._session.post(url, data=json.dumps(data_dict), timeout=self._timeout)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")

            response.raise_for_status()

            # Try to parse JSON response
            try:
                response_json = response.json()
                if pythonify:
                    return self._pythonify_response(response_json)
                else:
                    return response_json
            except json.JSONDecodeError:
                # If response is not JSON, return raw text
                return {"response": response.text}

        except requests.exceptions.ConnectionError as e:
            raise ConnectionError(f"Failed to connect to Serena service at {url}: {e}")
        except requests.exceptions.Timeout as e:
            raise ConnectionError(f"Request to {url} timed out: {e}")
        except requests.exceptions.HTTPError as e:
            if response is not None:
                # check for recoverable error (i.e. errors where the problem can be resolved by the caller or
                # other errors where the error text shall simply be passed on to the LLM).
                # The plugin returns 400 for such errors (typically illegal arguments, e.g. non-unique name path)
                # but only since version 2023.2.6
                if self.is_version_at_least(2023, 2, 6):
                    is_recoverable_error = response.status_code == 400
                else:
                    is_recoverable_error = True  # assume recoverable for older versions (mix of errors)
                if is_recoverable_error:
                    raise APIError(response)
                raise PluginServerError(f"API request failed with status {response.status_code}: {response.text}")
            raise PluginServerError(f"API request failed with HTTP error: {e}")
        except requests.exceptions.RequestException as e:
            raise SerenaClientError(f"Request failed: {e}")

View on GitHub (pinned to 7fcbca7e62)

Solutions

  1. Verify the JetBrains IDE with the Serena plugin is running and responsive
  2. Re-run project discovery (JetBrainsPluginClient.from_project) to refresh the service URL/port
  3. Restart the IDE if the plugin service appears hung
  4. Check proxy env vars (http_proxy/HTTPS_PROXY) aren't routing localhost requests away

Example fix

// before
NO_PROXY unset; requests routed via corporate proxy
// after
export NO_PROXY=localhost,127.0.0.1
Defensive patterns

Strategy: retry

Validate before calling

import requests
def service_reachable(url: str) -> bool:
    try:
        return requests.get(url, timeout=2, proxies={"http": None, "https": None}).ok
    except requests.exceptions.ConnectionError:
        return False

Try / catch

import time
for attempt in range(3):
    try:
        result = client.find_symbol(name_path="foo")
        break
    except ConnectionError as e:
        if "Failed to connect" in str(e) and attempt == 2:
            raise
        time.sleep(1)

Prevention

When it happens

Trigger: Any plugin HTTP call (client init, find_symbol, move, find_references, get_symbols_overview, get_supertypes) when the plugin's local server is down, the discovered port is stale, or the IDE is frozen/starting up.

Common situations: IDE crashed or was closed mid-session; cached service URL points to a dead port; firewall/proxy intercepting localhost requests; IDE still initializing after project open.

Related errors

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