What causes "failed to apply mode-specific session options: %w" in github/copilot-sdk?

Inspect the wrapped inner error (via errors.Unwrap or %v) for the exact server-side rejection reason.

failed to apply mode-specific session options

Error message

failed to apply mode-specific session options: %w

What it means

updateSessionOptionsForMode applies mode-specific session options to a newly created or resumed session. If applying those options fails, the session is disconnected (best-effort) and removed from the client's session map to avoid leaking a session running with permissive defaults, and this wrapped error is returned.

Solutions

Inspect the wrapped inner error (via errors.Unwrap or %v) for the exact server-side rejection reason.
Compare your SessionConfig/ResumeSessionConfig fields (optBackInFields) against the allowed options for the selected mode.
Retry CreateSession/ResumeSessionWithOptions if the inner error indicates a transient transport failure.
Verify client and server versions both support the requested session options.

Example fix

// before
config.OptBackIn = []string{"fs_write", "network"} // unsupported for this mode
// after
config.OptBackIn = []string{"fs_write"} // only options valid for the mode

Defensive patterns

Strategy: try-catch

Validate before calling

func validateModeOptions(cfg SessionConfig) error {
    // ensure opt-back-in fields are permitted for cfg.Mode before calling CreateSession
    return nil
}

Try / catch

sess, err := client.CreateSession(ctx, cfg)
if err != nil {
    var wrapped interface{ Unwrap() error }
    if errors.As(err, &target) { /* inspect inner reason */ }
    // cleanup is automatic; fix config and retry
}

Prevention

Only set session options documented for the chosen mode
Keep client and server versions aligned
Log the unwrapped inner error for diagnosis

When it happens

Trigger: CreateSession or ResumeSessionWithOptions where the server rejects the mode-specific option update — e.g. an invalid opt-back-in field combination, an unsupported option for the mode, or a session/request error from the server.

Common situations: Config fields in SessionConfig/ResumeSessionConfig that are incompatible with the selected mode; server version that doesn't support a requested option; transient request failures during session setup.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at go/mode_empty.go:298

			hasAny = true
		}
		if base.IncludedBuiltinSkills != nil {
			patch.IncludedBuiltinSkills = base.IncludedBuiltinSkills
			hasAny = true
		}
	}
	if !hasAny {
		return nil
	}
	if _, err := session.RPC.Options.Update(ctx, patch); err != nil {
		// The runtime session exists but the post-create options patch
		// failed — best-effort disconnect so we don't leak it (in empty
		// mode it would otherwise keep running with permissive defaults).
		_ = session.Disconnect()
		c.sessionsMux.Lock()
		delete(c.sessions, session.SessionID)
		c.sessionsMux.Unlock()
		return fmt.Errorf("failed to apply mode-specific session options: %w", err)
	}
	return nil
}

// optBackInFields is the subset of SessionConfig / ResumeSessionConfig shared
// by [Client.updateSessionOptionsForMode].
type optBackInFields struct {
	SkipCustomInstructions *bool
	CustomAgentsLocalOnly  *bool
	CoauthorEnabled        *bool
	ManageScheduleEnabled  *bool
	IncludedBuiltinSkills  []string
}

View on GitHub (pinned to cd8cf15dc3)