{"record":{"id":"6573ec18711e9d52","repo":"github/copilot-sdk","slug":"copilotclientoptions-optionname-cannot-be-combi","errorCode":null,"errorMessage":"CopilotClientOptions.${optionName} cannot be combined with CopilotClientOptions.setConnection(); configure the transport on the RuntimeConnection instead.","messagePattern":"CopilotClientOptions\\.(.+?) cannot be combined with CopilotClientOptions\\.setConnection\\(\\); configure the transport on the RuntimeConnection instead\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":358,"sourceCode":"            impliedUrl = uri.getUrl();\n            impliedToken = uri.getConnectionToken();\n            impliedUseStdio = false;\n        }\n\n        rejectConflict(\"CliPath\", options.getCliPath() != null && !options.getCliPath().equals(impliedPath));\n        rejectConflict(\"CliUrl\", options.getCliUrl() != null && !options.getCliUrl().isEmpty()\n                && !options.getCliUrl().equals(impliedUrl));\n        rejectConflict(\"Port\", options.getPort() != 0 && options.getPort() != impliedPort);\n        rejectConflict(\"TcpConnectionToken\",\n                options.getTcpConnectionToken() != null && !options.getTcpConnectionToken().equals(impliedToken));\n        rejectConflict(\"UseStdio\", !options.isUseStdio() && impliedUseStdio);\n        rejectConflict(\"CliArgs\", options.getCliArgs() != null\n                && !Arrays.asList(options.getCliArgs()).equals(impliedArgs == null ? List.of() : impliedArgs));\n    }\n\n    private static void rejectConflict(String optionName, boolean conflicting) {\n        if (conflicting) {\n            throw new IllegalArgumentException(\"CopilotClientOptions.\" + optionName\n                    + \" cannot be combined with CopilotClientOptions.setConnection(); configure the transport on the\"\n                    + \" RuntimeConnection instead.\");\n        }\n    }\n\n    /**\n     * Projects the configured connection onto the individual transport options so\n     * that the rest of the client sees a single, consistent view of the transport.\n     */\n    private static void applyConnection(CopilotClientOptions options, RuntimeConnection connection) {\n        if (connection instanceof StdioRuntimeConnection stdio) {\n            options.setUseStdio(true);\n            if (stdio.getPath() != null) {\n                options.setCliPath(stdio.getPath());\n            }\n            applyConnectionArgs(options, stdio.getArgs());\n        } else if (connection instanceof TcpRuntimeConnection tcp) {\n            options.setUseStdio(false);","sourceCodeStart":340,"sourceCodeEnd":376,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L340-L376","documentation":"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.","triggerScenarios":"new CopilotClient(...) with both setConnection(...) and any transport-affecting option set (e.g. setCliArgs(...) with values other than those implied by the connection).","commonSituations":"Migrating from option-based to connection-based configuration while keeping old setCliArgs calls; a shared builder that sets CliArgs unconditionally.","solutions":["Remove the conflicting CopilotClientOptions transport setter (e.g. CliArgs)","Move the configuration onto the RuntimeConnection object passed to setConnection()","Only set CopilotClientOptions transport fields when no explicit connection is supplied"],"exampleFix":"// before\noptions.setConnection(RuntimeConnection.forTcp(...));\noptions.setCliArgs(new String[]{\"--verbose\"});\n// after\nRuntimeConnection conn = RuntimeConnection.forTcp(...); // configure transport here\noptions.setConnection(conn);","handlingStrategy":"validation","validationCode":"if (options.getConnection() != null && options.getCliArgs() != null) throw new IllegalStateException(\"Configure transport on RuntimeConnection, not CopilotClientOptions\");","typeGuard":null,"tryCatchPattern":"try { new CopilotClient(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"cannot be combined with CopilotClientOptions.setConnection()\")) { /* drop the named option */ } else throw e; }","preventionTips":["When using setConnection(), configure all transport settings on the RuntimeConnection","Use one code path per configuration style"],"tags":["java","configuration","runtime-connection","conflict"],"backgroundTag":"conflicting-config-options","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}