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

Unwrap with %w (errors.Unwrap / errors.As) to find the root cause

failed to create session

Error message

failed to create session: %w

What it means

CreateSession wraps any error from the underlying RequestWithInlineResponse("session.create") call in this message. It is the generic failure envelope for the whole session-creation round trip, including transport errors, inline callback failures (490/491), and server-side rejections. Any registered session is unregistered before returning, so no partial state leaks.

Solutions

Unwrap with %w (errors.Unwrap / errors.As) to find the root cause
Verify the agent server is running and the client's connection options (address/port) are correct
Check whether the inner error is 'failed to parse sessionId' or 'did not include a sessionId' and follow those fixes
Retry once on transient network errors; check server logs for the session.create request

Example fix

// before
if err := create(); err != nil { return err }
// after
if err := create(); err != nil {
    var e *SessionError
    if errors.As(err, &e) { /* inspect root cause */ }
    return fmt.Errorf("create session: %w", err)
}

Defensive patterns

Strategy: try-catch

Validate before calling

conn, err := net.DialTimeout("tcp", serverAddr, 2*time.Second)
if err != nil { return fmt.Errorf("agent server unreachable at %s", serverAddr) }
conn.Close()

Try / catch

s, err := client.CreateSession(ctx, opts)
if err != nil {
    root := errors.Unwrap(err)
    if isTransientNetErr(root) { /* retry with backoff */ }
    return fmt.Errorf("create session: %w", err)
}

Prevention

Health-check the server before creating sessions
Retry transient network errors with backoff
Always unwrap wrapped errors to find the real cause

When it happens

Trigger: Any failure inside CreateSession's RequestWithInlineResponse call: connection failure, timeout, server error response, or an error returned by the inline sessionId-parsing callback.

Common situations: Server not running or wrong port; the connection dropped mid-request; the inline callback returned errors 490/491 which surface wrapped here; auth failure rejected by the server.

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/ddeca2c1afea6bcf. Report an issue: GitHub.

Appendix: source

Thrown at go/client.go:1144

			if early.SessionID == "" {
				return fmt.Errorf("session.create response did not include a sessionId")
			}
			s, err := initializeSession(early.SessionID)
			if err != nil {
				return err
			}
			session = s
			registeredSessionID = early.SessionID
			return nil
		}
	}

	result, err := c.client.RequestWithInlineResponse(ctx, "session.create", req, inlineCb)
	if err != nil {
		if registeredSessionID != "" {
			unregisterSession(registeredSessionID, session)
		}
		return nil, fmt.Errorf("failed to create session: %w", err)
	}

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

	if session == nil {
		return nil, fmt.Errorf("session.create response did not include a sessionId")
	}

	if localSessionID != "" && response.SessionID != "" && response.SessionID != localSessionID {
		unregisterSession(registeredSessionID, session)
		return nil, fmt.Errorf("session.create returned sessionId %s but the caller requested %s", response.SessionID, localSessionID)
	}

View on GitHub (pinned to cd8cf15dc3)