{"record":{"id":"00d47d423d2eb25f","repo":"can1357/oh-my-pi","slug":"rpc-process-stopped-before-ready-error-stderr","errorCode":null,"errorMessage":"RPC process stopped before ready: {error}. Stderr: {stderr}","messagePattern":"RPC process stopped before ready: (.+?)\\. Stderr: (.+?)","errorType":"exception","errorClass":"RpcProcessExitError","httpStatus":null,"severity":"critical","filePath":"python/omp-rpc/src/omp_rpc/client.py","lineNumber":641,"sourceCode":"        )\n        self._stdout_thread.start()\n        self._stderr_thread.start()\n\n        if not self._ready.wait(self._startup_timeout):\n            stderr = self.stderr\n            self.stop()\n            raise RpcTimeoutError(\n                f\"Timed out waiting for RPC ready signal. Stderr: {stderr}\"\n            )\n\n        if not self._ready_received:\n            error = self._closed_error\n            stderr = self.stderr\n            self.stop()\n            if isinstance(error, RpcError):\n                raise error\n            if error is not None:\n                raise RpcProcessExitError(\n                    f\"RPC process stopped before ready: {error}. Stderr: {stderr}\"\n                ) from error\n            raise RpcTimeoutError(\n                f\"Timed out waiting for RPC ready signal. Stderr: {stderr}\"\n            )\n\n        ready_event = self._ready_event\n        if (\n            ready_event is not None\n            and ready_event.supported_protocol_versions is not None\n            and 2 in ready_event.supported_protocol_versions\n            and ready_event.max_frame_bytes == _MAX_RPC_FRAME_BYTES\n            and ready_event.max_reassembled_frame_bytes == _MAX_RPC_REASSEMBLED_BYTES\n        ):\n            try:\n                self._protocol_v2_enabled = True\n                negotiation = self._request(\"negotiate_protocol\", protocolVersion=2)\n                if negotiation.get(\"protocolVersion\") != 2:","sourceCodeStart":623,"sourceCodeEnd":659,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/python/omp-rpc/src/omp_rpc/client.py#L623-L659","documentation":"During start(), if the child process closes (exits or errors) before sending the ready signal, the client raises the underlying RpcError if it is one, otherwise wraps it in RpcProcessExitError with the captured stderr. This means the agent died during startup rather than merely being slow.","triggerScenarios":"Agent subprocess crashes/exits during startup: bad command path, missing interpreter/module, unhandled exception in the agent, invalid config read at boot, or the OS killing the process (OOM, permissions).","commonSituations":"Typos in the agent command or venv path; Python version mismatch; corrupt config file parsed at startup; missing API keys causing early fatal error; binary incompatible with the OS/arch.","solutions":["Inspect the wrapped error and Stderr text in the message — it contains the child's actual crash output.","Run the agent command manually in a terminal to reproduce and see the startup error directly.","Fix the agent command/path/config (correct venv, interpreter, module, API keys).","Check for environment issues: permissions, OOM kills, missing shared libraries.","Verify agent and client versions are compatible."],"exampleFix":"// before: command points at a nonexistent entrypoint\nRpcClient(command=[\"python\", \"-m\", \"agent_server_typo\"])\n\n// after\nRpcClient(command=[\"python\", \"-m\", \"agent_server\"])","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    client.start()\nexcept RpcProcessExitError as exc:\n    logger.error(\"agent died during startup: %s\", exc)\n    raise  # crash output is embedded; fix the agent command/config","preventionTips":["Test the agent command standalone before wiring it into the client","Validate config files and env (keys, paths, interpreter) before startup","Keep agent and client versions compatible","Monitor for OOM/permission kills in the deployment environment"],"tags":["rpc","subprocess","process-exit","startup"],"backgroundTag":"process-exited-unexpectedly","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}