oraios/serena · error · ConnectionError

Request to {url} timed out: {e}

Error message

Request to {url} timed out: {e}

What it means

_make_request maps requests.exceptions.Timeout to ConnectionError('Request to {url} timed out'). The Serena plugin service accepted the connection but did not respond within the configured timeout — typically the IDE is busy (indexing, long operation) or the requested analysis is heavy.

Source

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

                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}")

    @staticmethod

View on GitHub (pinned to 7fcbca7e62)

Solutions

  1. Retry the request once the IDE finishes indexing (watch the status bar)
  2. Increase the plugin client request timeout if configurable
  3. Reduce operation scope (narrower symbol name/path depth)
  4. Restart the IDE if it's unresponsive to plugin requests
Defensive patterns

Strategy: retry

Validate before calling

import time
# avoid calling while the IDE is indexing: poll a cheap endpoint first
def wait_until_ready(client, attempts: int = 10):
    for _ in range(attempts):
        try:
            client.get_symbols_overview(relative_path=".")
            return
        except ConnectionError:
            time.sleep(2)
    raise TimeoutError("Serena plugin service not responding")

Try / catch

try:
    syms = client.find_symbol(name_path="Foo")
except ConnectionError as e:
    if "timed out" in str(e):
        time.sleep(2)
        syms = client.find_symbol(name_path="Foo")  # single retry
    else:
        raise

Prevention

When it happens

Trigger: find_symbol/move/get_supertypes/etc. issued while the IDE is indexing, a modal dialog blocks the IDE's request handling, or the operation itself (e.g. wide symbol search) exceeds the client timeout.

Common situations: Large projects still indexing after open; IDE paused on breakpoint or unfocused power-save mode; slow machine; timeout too small for large codebase operations.

Understand the failure class

Related errors

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