GitHubToken and UseLoggedInUser cannot be used with…

Error message

GitHubToken and UseLoggedInUser cannot be used with URIConnection (external runtime manages its own auth)

What it means

NewClient panics when connecting to an external runtime via URIConnection while also supplying auth options (GitHubToken or UseLoggedInUser). An external server manages its own authentication; per-client auth supplied by the SDK client would conflict with or be ignored by it, so the SDK rejects the combination.

Solutions

Remove GitHubToken and UseLoggedInUser from the options when using URIConnection; authenticate at the external runtime itself.
If you need the SDK to manage auth, switch to StdioConnection (child-process transport) instead.
Conditionally build the Options struct based on whether you're attaching or spawning.

Example fix

// before
client := clientpkg.NewClient(&clientpkg.Options{
    Connection:  clientpkg.URIConnection{URL: "http://127.0.0.1:4141"},
    GitHubToken: token,
})
// after
client := clientpkg.NewClient(&clientpkg.Options{
    Connection: clientpkg.URIConnection{URL: "http://127.0.0.1:4141"},
    // auth is managed by the external runtime
})

Defensive patterns

Strategy: validation

Validate before calling

if _, ok := opts.Connection.(clientpkg.URIConnection); ok && (opts.GitHubToken != "" || opts.UseLoggedInUser != nil) {
    return fmt.Errorf("auth options are not allowed with URIConnection")
}

Type guard

func isExternalServer(c clientpkg.RuntimeConnection) bool { _, ok := c.(clientpkg.URIConnection); return ok }

Prevention

Keep auth options only in the spawn-a-runtime code path.
Authenticate the external server itself, not the attaching client.
Build options conditionally based on attach-vs-spawn mode.

When it happens

Trigger: Calling NewClient with Connection: URIConnection{URL: ...} (which sets client.isExternalServer) and either Options.GitHubToken != "" or Options.UseLoggedInUser != nil. Panic at go/client.go:298.

Common situations: Shared client-construction helper that always sets GitHubToken, then reused for an attach-to-external-server code path; copying auth settings from a stdio-based setup into a URIConnection setup.

Related errors

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

Appendix: source

Thrown at go/client.go:298

		client.useStdio = false
		client.tcpConnectionToken = conn.ConnectionToken
	case InProcessConnection:
		client.useStdio = false
		client.useInProcess = true
	default:
		panic(fmt.Sprintf("unknown RuntimeConnection type: %T", connection))
	}

	// Validate transport-specific option constraints (fail loud). The in-process
	// transport loads the runtime into this process, whose single environment
	// block, process-global working directory, and shared telemetry state cannot
	// carry per-client values. Child-process transports may set env via either
	// the client-level option or the connection, but not both.
	validateEnvironmentOptions(connection, &opts)

	// Validate auth options when connecting to an external runtime.
	if client.isExternalServer && (opts.GitHubToken != "" || opts.UseLoggedInUser != nil) {
		panic("GitHubToken and UseLoggedInUser cannot be used with URIConnection (external runtime manages its own auth)")
	}

	// For child-process transports, a connection-level env takes precedence over
	// the client-level env (setting both was rejected above). Resolve it before
	// defaulting so an explicit empty connection env stays authoritative.
	if cp, ok := connection.(childProcessConnection); ok {
		if env := cp.connEnv(); env != nil {
			opts.Env = env
		}
	}

	// Default Env to current environment if not set
	if opts.Env == nil {
		opts.Env = os.Environ()
	}

	// Check the effective environment for a child-process runtime override.
	if client.cliPath == "" && !client.useInProcess {

View on GitHub (pinned to cd8cf15dc3)