What causes "failed to resume session: %w" in github/copilot-sdk?

Unwrap the error (errors.Unwrap/errors.As) to identify the root cause

failed to resume session

Error message

failed to resume session: %w

What it means

ResumeSessionWithOptions wraps any error from the underlying "session.resume" request in this message and restores the previously replaced session before returning. It is the generic failure envelope for the resume round trip — transport errors, timeouts, and server-side rejections all surface here wrapped via %w.

Solutions

Unwrap the error (errors.Unwrap/errors.As) to identify the root cause
Verify the session ID exists server-side; create a new session if the server lost state after restart
Check connectivity to the agent server and that ensureConnected succeeded
Retry with backoff for transient network failures; check server logs for the session.resume rejection reason

Example fix

// before
sess, err := client.ResumeSession(ctx, id)
// after
sess, err := client.ResumeSession(ctx, id)
if err != nil {
    if isSessionGone(err) { sess, err = client.CreateSession(ctx, opts) }
    return err
}

Defensive patterns

Strategy: try-catch

Validate before calling

if sessionID == "" { return errors.New("cannot resume: empty session ID") }
conn, err := net.DialTimeout("tcp", serverAddr, 2*time.Second)
if err != nil { return fmt.Errorf("agent server unreachable: %w", err) }
conn.Close()

Try / catch

sess, err := client.ResumeSession(ctx, id)
if err != nil {
    root := errors.Unwrap(err)
    if isNotFound(root) { sess, err = client.CreateSession(ctx, opts) } // server lost state
    else if isTransient(root) { /* retry with backoff */ }
    return err
}

Prevention

Persist session IDs and verify they still exist before resuming
Fall back to CreateSession when the server no longer knows the session
Retry transient network errors with exponential backoff

When it happens

Trigger: Calling ResumeSession/ResumeSessionWithOptions when c.client.Request(ctx, "session.resume", req) fails: server unreachable, session ID unknown to the server, connection reset, or a resume rejected server-side.

Common situations: Resuming a session after the server restarted and lost its state; wrong/stale session ID; network interruption; server rejecting resume due to version or permission issues.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

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

Appendix: source

Thrown at go/client.go:1470

	if c.options.SessionFS != nil {
		if config.CreateSessionFSProvider == nil {
			restoreReplacedSession()
			return nil, fmt.Errorf("CreateSessionFSProvider is required in session config when SessionFS is enabled in client options")
		}
		provider := config.CreateSessionFSProvider(session)
		if c.options.SessionFS.Capabilities != nil && c.options.SessionFS.Capabilities.Sqlite {
			if _, ok := provider.(SessionFSSqliteProvider); !ok {
				restoreReplacedSession()
				return nil, fmt.Errorf("SessionFS capabilities declare SQLite support but the provider does not implement SessionFSSqliteProvider")
			}
		}
		session.clientSessionAPIs.SessionFS = newSessionFSAdapter(provider)
	}

	result, err := c.client.Request(ctx, "session.resume", req)
	if err != nil {
		restoreReplacedSession()
		return nil, fmt.Errorf("failed to resume session: %w", err)
	}

	var response resumeSessionResponse
	if err := json.Unmarshal(result, &response); err != nil {
		restoreReplacedSession()
		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
	}

	if config.OnMCPAuthRequest != nil {
		if _, err := c.client.Request(ctx, "session.eventLog.registerInterest", map[string]any{
			"sessionId": sessionID,
			"eventType": "mcp.oauth_required",
		}); err != nil {
			restoreReplacedSession()
			return nil, err
		}
	}

View on GitHub (pinned to cd8cf15dc3)