github/copilot-sdk · error · IllegalArgumentException

CopilotClientOptions.

Error message

CopilotClientOptions.${optionName} is not supported with RuntimeConnection.forInProcess(): the in-process runtime shares the host process, so per-client values cannot be honored; ${remedy}.

What it means

With RuntimeConnection.forInProcess(), the runtime shares the host process, so per-client options like CliArgs cannot be honored (there is no separate CLI process to receive them). validateEnvironmentOptions calls rejectInProcessOption for each such option present and throws IllegalArgumentException including a remedy hint.

Solutions

1. Remove the unsupported option (e.g. clear CliArgs)
2. Follow the remedy in the message — use the typed client options or in-process equivalents
3. Use a stdio/TCP connection instead if you genuinely need per-process CLI arguments

Example fix

// before
options.setConnection(RuntimeConnection.forInProcess());
options.setCliArgs(new String[]{"--verbose"});
// after
options.setConnection(RuntimeConnection.forInProcess()); // no per-process options
// configure via typed client options instead

if (connection.isInProcess() && options.getCliArgs() != null && options.getCliArgs().length > 0) throw new IllegalStateException("CliArgs unsupported with forInProcess()");

try { new CopilotClient(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("not supported with RuntimeConnection.forInProcess()")) { /* remove the named option */ } else throw e; }

When it happens

Trigger: new CopilotClient(...) where the resolved/supplied connection is RuntimeConnection.forInProcess() and options set a per-client value such as non-empty CliArgs.

Common situations: Defaults from a shared options builder applied to an embedded in-process client; setting CLI tuning flags expecting them to affect the in-process runtime.

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

Appendix: source

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

     */
    private static void validateEnvironmentOptions(CopilotClientOptions options, RuntimeConnection connection) {
        if (!(connection instanceof InProcessRuntimeConnection)) {
            return;
        }

        rejectInProcessOption("Environment", options.getEnvironment() != null && !options.getEnvironment().isEmpty(),
                "set the variables on the host process environment instead");
        rejectInProcessOption("Telemetry", options.getTelemetry() != null,
                "configure telemetry through the host process environment instead");
        rejectInProcessOption("Cwd", options.getCwd() != null,
                "set the process working directory before creating the client instead");
        rejectInProcessOption("CliArgs", options.getCliArgs() != null && options.getCliArgs().length > 0,
                "use the typed client options instead");
    }

    private static void rejectInProcessOption(String optionName, boolean present, String remedy) {
        if (present) {
            throw new IllegalArgumentException("CopilotClientOptions." + optionName
                    + " is not supported with RuntimeConnection.forInProcess(): the in-process runtime shares the host"
                    + " process, so per-client values cannot be honored; " + remedy + ".");
        }
    }

    /**
     * Duplex streams of an in-process runtime, together with the resource that owns
     * its lifetime.
     *
     * @param receiveStream
     *            stream carrying messages from the runtime
     * @param sendStream
     *            stream carrying messages to the runtime
     * @param host
     *            resource closed when the client stops
     */
    record InProcessTransport(InputStream receiveStream, OutputStream sendStream, AutoCloseable host) {
    }

View on GitHub (pinned to cd8cf15dc3)