github/copilot-sdk · error · IllegalArgumentException

CopilotClientOptions.

Error message

CopilotClientOptions.${optionName} cannot be combined with CopilotClientOptions.setConnection(); configure the transport on the RuntimeConnection instead.

What it means

When a RuntimeConnection is explicitly supplied via CopilotClientOptions.setConnection(), transport-level options (like CliArgs) set on CopilotClientOptions would be ambiguous — the library requires all transport configuration to live on the RuntimeConnection itself. validateConnectionConflicts calls rejectConflict for each conflicting option and throws IllegalArgumentException naming the offending option.

Solutions

1. Remove the conflicting CopilotClientOptions transport setter (e.g. CliArgs)
2. Move the configuration onto the RuntimeConnection object passed to setConnection()
3. Only set CopilotClientOptions transport fields when no explicit connection is supplied

Example fix

// before
options.setConnection(RuntimeConnection.forTcp(...));
options.setCliArgs(new String[]{"--verbose"});
// after
RuntimeConnection conn = RuntimeConnection.forTcp(...); // configure transport here
options.setConnection(conn);

if (options.getConnection() != null && options.getCliArgs() != null) throw new IllegalStateException("Configure transport on RuntimeConnection, not CopilotClientOptions");

try { new CopilotClient(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("cannot be combined with CopilotClientOptions.setConnection()")) { /* drop the named option */ } else throw e; }

When it happens

Trigger: new CopilotClient(...) with both setConnection(...) and any transport-affecting option set (e.g. setCliArgs(...) with values other than those implied by the connection).

Common situations: Migrating from option-based to connection-based configuration while keeping old setCliArgs calls; a shared builder that sets CliArgs unconditionally.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• CliUrl is mutually exclusive with CliPath
• GitHubToken and UseLoggedInUser cannot be used with CliUrl…
• TcpConnectionToken must be a non-empty string
• TcpConnectionToken cannot be used with UseStdio = true
• CopilotClient was created with Mode = EMPTY but neither…

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CopilotClient.java:358

            impliedUrl = uri.getUrl();
            impliedToken = uri.getConnectionToken();
            impliedUseStdio = false;
        }

        rejectConflict("CliPath", options.getCliPath() != null && !options.getCliPath().equals(impliedPath));
        rejectConflict("CliUrl", options.getCliUrl() != null && !options.getCliUrl().isEmpty()
                && !options.getCliUrl().equals(impliedUrl));
        rejectConflict("Port", options.getPort() != 0 && options.getPort() != impliedPort);
        rejectConflict("TcpConnectionToken",
                options.getTcpConnectionToken() != null && !options.getTcpConnectionToken().equals(impliedToken));
        rejectConflict("UseStdio", !options.isUseStdio() && impliedUseStdio);
        rejectConflict("CliArgs", options.getCliArgs() != null
                && !Arrays.asList(options.getCliArgs()).equals(impliedArgs == null ? List.of() : impliedArgs));
    }

    private static void rejectConflict(String optionName, boolean conflicting) {
        if (conflicting) {
            throw new IllegalArgumentException("CopilotClientOptions." + optionName
                    + " cannot be combined with CopilotClientOptions.setConnection(); configure the transport on the"
                    + " RuntimeConnection instead.");
        }
    }

    /**
     * Projects the configured connection onto the individual transport options so
     * that the rest of the client sees a single, consistent view of the transport.
     */
    private static void applyConnection(CopilotClientOptions options, RuntimeConnection connection) {
        if (connection instanceof StdioRuntimeConnection stdio) {
            options.setUseStdio(true);
            if (stdio.getPath() != null) {
                options.setCliPath(stdio.getPath());
            }
            applyConnectionArgs(options, stdio.getArgs());
        } else if (connection instanceof TcpRuntimeConnection tcp) {
            options.setUseStdio(false);

View on GitHub (pinned to cd8cf15dc3)