{"record":{"id":"6d896f0b7840623a","repo":"github/copilot-sdk","slug":"client-not-connected-call-start-first","errorCode":null,"errorMessage":"Client not connected; call start() first","messagePattern":"Client not connected; call start\\(\\) first","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":1456,"sourceCode":"     * Provides strongly-typed access to all server-level API namespaces such as\n     * {@code models}, {@code tools}, {@code account}, and {@code mcp}.\n     * <p>\n     * Example usage:\n     *\n     * <pre>{@code\n     * client.start().get();\n     * var models = client.getRpc().models.list().get();\n     * }</pre>\n     *\n     * @return the server-level typed RPC client\n     * @throws IllegalStateException\n     *             if the client is not connected; call {@link #start()} first\n     * @since 1.0.0\n     */\n    public ServerRpc getRpc() {\n        CompletableFuture<Connection> future = connectionFuture;\n        if (future == null || !future.isDone() || future.isCompletedExceptionally()) {\n            throw new IllegalStateException(\"Client not connected; call start() first\");\n        }\n        return future.join().serverRpc();\n    }\n\n    /**\n     * Pings the server to check connectivity.\n     * <p>\n     * This can be used to verify that the server is responsive and to check the\n     * protocol version.\n     *\n     * @param message\n     *            an optional message to echo back\n     * @return a future that resolves with the ping response\n     * @see PingResponse\n     */\n    public CompletableFuture<PingResponse> ping(String message) {\n        return ensureConnected().thenCompose(connection -> connection.rpc.invoke(\"ping\",\n                Map.of(\"message\", message != null ? message : \"\"), PingResponse.class));","sourceCodeStart":1438,"sourceCodeEnd":1474,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L1438-L1474","documentation":"getRpc() returns the ServerRpc handle only after start() has successfully established a connection. If the connection future is null, still pending, or completed exceptionally, the client has no RPC channel and IllegalStateException is thrown.","triggerScenarios":"Calling client.getRpc() before start(), while start()'s connection handshake is still in flight, or after connection failed (future completed exceptionally).","commonSituations":"Forgetting start() in new integration code; racing getRpc() immediately after start() without awaiting the returned future; server binary failed to launch so the connection never completes.","solutions":["Call start() and await its completion before getRpc(): client.start().join() (or thenAccept)","Check the exception cause of the failed connection future (start().exceptionally) — likely server launch failure","Gate all RPC usage behind a readiness flag set after start() completes"],"exampleFix":"// before\nServerRpc rpc = client.getRpc();\n// after\nclient.start().join();\nServerRpc rpc = client.getRpc();","handlingStrategy":"validation","validationCode":"if (client.getConnectionFuture() == null || !client.getConnectionFuture().isDone()) {\n    client.start().join(); // or await readiness signal\n}","typeGuard":null,"tryCatchPattern":"try {\n    ServerRpc rpc = client.getRpc();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"not connected\")) {\n        client.start().join();\n    }\n}","preventionTips":["Always call start() and await completion in initialization code","Gate RPC access behind an application readiness flag","Diagnose start() failures early instead of letting later getRpc() calls surface them"],"tags":["lifecycle","rpc","not-connected"],"backgroundTag":"invalid-state-transition","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}