What causes "session error: %s" in github/copilot-sdk?

Inspect the inner %s message for the actual CLI-reported cause and fix that (model name, auth, network).

session error

Error message

session error: %s

What it means

This error is created when the session's event dispatcher receives a *SessionErrorData event from the Copilot CLI process and converts it into a Go error carrying the CLI's message. It represents a fatal/terminal error reported by the underlying CLI session (crash, protocol failure, model or configuration problem), surfaced to callers of Session.SendAndWait via the errCh. The wrapping select-with-default means the error is dropped if no one is listening on errCh.

Solutions

Inspect the inner %s message for the actual CLI-reported cause and fix that (model name, auth, network).
Check the installed copilot CLI version matches what the Go SDK expects; upgrade the CLI and SDK together.
Verify authentication (run the CLI manually once) and network/proxy settings before starting the session.
Enable SDK/CLI debug logging to capture the full session.error payload.

Example fix

// before
result, err := session.SendPromptAndWait(ctx, prompt)
// after
result, err := session.SendPromptAndWait(ctx, prompt)
if err != nil {
    var serr *copilot.SessionError
    if errors.As(err, &serr) {
        log.Printf("CLI session failed: %v", err) // diagnose underlying CLI cause
    }
}

Defensive patterns

Strategy: try-catch

Try / catch

result, err := session.SendPromptAndWait(ctx, prompt)
if err != nil {
    if strings.HasPrefix(err.Error(), "session error:") {
        // CLI-reported session failure; log err and recreate the session
    }
}

Prevention

Keep CLI and SDK versions in lockstep
Validate auth and model configuration before creating sessions
Subscribe to Session.On events to observe session.error data directly
Test CLI connectivity standalone before embedding in the app

When it happens

Trigger: The CLI sends a session.error event during a Session.SendAndWait/SendPromptAndWait call; the message text is whatever the CLI attached as SessionErrorData.Message.

Common situations: The copilot CLI binary crashes or exits mid-conversation; invalid model or session configuration rejected server-side; network/auth failures reported by the CLI as a session-level error; CLI protocol version mismatches between SDK and installed CLI.

Related errors

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

Appendix: source

Thrown at go/session.go:523

	unsubscribe := s.On(func(event SessionEvent) {
		switch d := event.Data.(type) {
		case *AssistantMessageData:
			mu.Lock()
			eventCopy := event
			lastAssistantMessage = &eventCopy
			mu.Unlock()
		case *SessionIdleData:
			if d.Mode != nil && *d.Mode == SessionModeAutopilot {
				break
			}
			select {
			case idleCh <- struct{}{}:
			default:
			}
		case *SessionErrorData:
			select {
			case errCh <- fmt.Errorf("session error: %s", d.Message):
			default:
			}
		}
	})
	defer unsubscribe()

	_, err := s.Send(ctx, options)
	if err != nil {
		return nil, err
	}

	select {
	case <-idleCh:
		mu.Lock()
		result := lastAssistantMessage
		mu.Unlock()
		return result, nil
	case err := <-errCh:

View on GitHub (pinned to cd8cf15dc3)