What causes "client not connected" in github/copilot-sdk?

Ensure Connect (or the equivalent initialization call) succeeded before calling Ping

client not connected

Error message

client not connected

What it means

Ping returns this error when the Client's underlying JSON-RPC client (c.client) is nil, i.e. no connection to the agent backend has ever been established. Ping cannot send a request without a transport, so it fails fast instead of panicking on a nil client.

Solutions

Ensure Connect (or the equivalent initialization call) succeeded before calling Ping
Check the error returned at construction time — a failed spawn of the agent binary leaves client nil
Re-create or reconnect the client if it was closed, then Ping again
Guard health-check loops so they skip Ping while the client is disconnected

Example fix

// before
resp, err := client.Ping(ctx, "health")
// after
if err := client.Connect(ctx); err != nil {
    return fmt.Errorf("connect: %w", err)
}
resp, err := client.Ping(ctx, "health")

Defensive patterns

Strategy: try-catch

Validate before calling

// guard before calling
if client == nil {
    return fmt.Errorf("client not initialized")
}

Type guard

func isConnected(c *acp.Client) bool {
    return c != nil && !c.IsClosed() // check your wrapper's connection state
}

Try / catch

resp, err := client.Ping(ctx, "health")
if err != nil {
    if strings.Contains(err.Error(), "client not connected") {
        // reconnect then retry once
        if cerr := client.Connect(ctx); cerr == nil {
            resp, err = client.Ping(ctx, "health")
        }
    }
    if err != nil { return err }
}

Prevention

Always call Connect and check its error before any client method
Track client lifecycle in one place so health checks wait for readiness
Never reuse a client after Close — create a new one
Fail fast at startup if Connect fails instead of keeping a nil-client wrapper

When it happens

Trigger: Calling Ping on a Client that was created without a successful Connect/start (e.g. constructed via a constructor that defers connection, or after an explicit close/disconnect).

Common situations: Health-check goroutines starting before client.Connect completes; reusing a client after Close; error swallowed during initialization so the app kept a disconnected client.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/fc8cc41c3e1f26b5. Report an issue: GitHub.

Appendix: source

Thrown at go/client.go:1859

	return c.actualPort
}

// Ping sends a ping request to the server to verify connectivity.
//
// The message parameter is optional and will be echoed back in the response.
// Returns a PingResponse containing the message and server timestamp, or an error.
//
// Example:
//
//	resp, err := client.Ping(context.Background(), "health check")
//	if err != nil {
//	    log.Printf("Server unreachable: %v", err)
//	} else {
//	    log.Printf("Server responded at %s", resp.Timestamp)
//	}
func (c *Client) Ping(ctx context.Context, message string) (*PingResponse, error) {
	if c.client == nil {
		return nil, fmt.Errorf("client not connected")
	}

	result, err := c.client.Request(ctx, "ping", pingRequest{Message: message})
	if err != nil {
		return nil, err
	}

	var response PingResponse
	if err := json.Unmarshal(result, &response); err != nil {
		return nil, err
	}
	return &response, nil
}

// GetStatus returns CLI status including version and protocol information
func (c *Client) GetStatus(ctx context.Context) (*GetStatusResponse, error) {
	if c.client == nil {
		return nil, fmt.Errorf("client not connected")

View on GitHub (pinned to cd8cf15dc3)