can1357/oh-my-pi · error · RpcTimeoutError

Timed out waiting for RPC ready signal. Stderr: {stderr}

Error message

Timed out waiting for RPC ready signal. Stderr: {stderr}

What it means

start() waits up to _startup_timeout for the agent subprocess to signal readiness on stdout. If the ready signal never arrives in time, the client stops the process and raises RpcTimeoutError including captured stderr to aid diagnosis.

Source

Thrown at python/omp-rpc/src/omp_rpc/client.py:630

            bufsize=1,
            start_new_session=True,
        )
        self._process = process
        self._pgid = _process_group_id(process)

        self._stdout_thread = threading.Thread(
            target=self._read_stdout_loop, name="omp-rpc-stdout", daemon=True
        )
        self._stderr_thread = threading.Thread(
            target=self._read_stderr_loop, name="omp-rpc-stderr", daemon=True
        )
        self._stdout_thread.start()
        self._stderr_thread.start()

        if not self._ready.wait(self._startup_timeout):
            stderr = self.stderr
            self.stop()
            raise RpcTimeoutError(
                f"Timed out waiting for RPC ready signal. Stderr: {stderr}"
            )

        if not self._ready_received:
            error = self._closed_error
            stderr = self.stderr
            self.stop()
            if isinstance(error, RpcError):
                raise error
            if error is not None:
                raise RpcProcessExitError(
                    f"RPC process stopped before ready: {error}. Stderr: {stderr}"
                ) from error
            raise RpcTimeoutError(
                f"Timed out waiting for RPC ready signal. Stderr: {stderr}"
            )

        ready_event = self._ready_event

View on GitHub (pinned to 9690622007)

Solutions

Read the Stderr embedded in the error — it almost always names the real startup problem (import error, missing binary, auth prompt).
Increase the startup timeout option if the agent legitimately needs longer (slow disks, CI).
Verify the configured agent command runs correctly standalone and emits the ready frame.
Ensure nothing else drains the child's stdout and stdin is provided/closed as the protocol expects.
Pre-warm dependencies (model downloads, venvs) before starting the client in latency-sensitive paths.

Example fix

# before
default: short startup timeout on slow machine
client = RpcClient(command=..., startup_timeout=5)

# after
client = RpcClient(command=..., startup_timeout=60)

Defensive patterns

Strategy: try-catch

Try / catch

try:
    client.start()
except RpcTimeoutError as exc:
    logger.error("agent startup timed out; stderr=%s", exc)
    # retry with longer timeout or surface stderr to the user

Prevention

Set a startup_timeout appropriate for slow environments (CI, cold caches)
Verify the agent emits its ready frame promptly and flushes stdout
Pre-warm dependencies before starting the client
Always read the stderr included in the timeout error

When it happens

Trigger: Agent binary slow to initialize (cold start, heavy imports), wrong command/path causing the process to hang or run a different program, ready signal lost due to stdout being consumed elsewhere, or startup_timeout too small for the environment.

Common situations: First-run model/native dependency downloads delaying startup; slow containers or CI machines; agent stuck prompting for input on stdin; wrong interpreter or missing module leaving the process blocked.

Understand the failure class

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

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/784f5c4ed3e3b872. Report an issue: GitHub.