oraios/serena · error · RuntimeError

Could not connect to {self._connection_info.host}:{self._con

Error message

Could not connect to {self._connection_info.host}:{self._connection_info.port} within {self._connection_info.connection_timeout}s

What it means

RuntimeError raised in _start of TCPLanguageServer (src/solidlsp/ls_process.py:721) when a TCP connection to the language server could not be established within connection_timeout seconds. The last OSError from the socket attempts is attached via `from`.

Source

Thrown at src/solidlsp/ls_process.py:721

    def is_running(self) -> bool:
        return self._sock is not None

    def _start(self) -> None:
        deadline = time.monotonic() + self._connection_info.connection_timeout
        last_exc: Exception | None = None
        while True:
            try:
                sock = socket.create_connection((self._connection_info.host, self._connection_info.port), timeout=5.0)
                sock.settimeout(None)
                self._sock = sock
                self._file = sock.makefile("rb")
                log.info("TCPLanguageServer connected to %s:%d", self._connection_info.host, self._connection_info.port)
                break
            except OSError as exc:
                last_exc = exc
                remaining = deadline - time.monotonic()
                if remaining <= 0:
                    raise RuntimeError(
                        f"Could not connect to {self._connection_info.host}:{self._connection_info.port} "
                        f"within {self._connection_info.connection_timeout}s"
                    ) from last_exc
                log.debug(
                    "TCPLanguageServer: connection failed (%s), retrying in %.1fs (%.0fs left)",
                    exc,
                    self._connection_info.retry_interval,
                    remaining,
                )
                time.sleep(min(self._connection_info.retry_interval, remaining))

        threading.Thread(
            target=self._read_loop,
            name=f"LSP-tcp-reader:{self.ls_id.value}",
            daemon=True,
        ).start()

    def _stop(self, timeout: float) -> None:

View on GitHub (pinned to 7fcbca7e62)

Solutions

Increase connection_timeout in the connection info to accommodate slow server startup.
Verify the server process actually started (check for a sibling process-terminated error) and is listening on the configured host/port.
Check firewall/security software and container network settings blocking the port.
Confirm host/port values match the server's own listen configuration.

Example fix

// before
ConnectionInfo(host="127.0.0.1", port=9999, connection_timeout=1.0)
// after
ConnectionInfo(host="127.0.0.1", port=9999, connection_timeout=30.0)

Defensive patterns

Strategy: validation

Validate before calling

import socket
s = socket.socket()
s.settimeout(2)
try:
    s.connect((host, port))
    s.close()
except OSError as e:
    raise ConfigError(f"port {port} unreachable: {e}")

Type guard

def conn_info_ok(info: ConnectionInfo) -> bool:
    return info.connection_timeout >= 10 and info.port > 0

Try / catch

try:
    ls = TcpLanguageServer(conn_info)
except RuntimeError as e:
    if "Could not connect" in str(e):
        conn_info.connection_timeout *= 4
        ls = TcpLanguageServer(conn_info)
    else:
        raise

Prevention

Set generous connection_timeout on slow or loaded machines
Verify host/port match the server's listen configuration
Check firewall/container networking before deployment
Confirm the server process stays alive while connecting

When it happens

Trigger: Launching a TCP-based language server that fails to bind/listen on the configured host:port, binds on a different interface than expected, or takes longer than connection_timeout to become ready.

Common situations: Firewall or container networking blocking localhost ports; server configured to listen on a different port/host; slow startup on loaded machines exceeding the timeout; host mismatch (127.0.0.1 vs 0.0.0.0 in containers).

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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