github/copilot-sdk · error · IllegalArgumentException

Invalid value ' '. Expected 'inprocess', 'stdio', or unset.

Error message

Invalid ${DEFAULT_CONNECTION_ENV_VAR} value '${envValue}'. Expected 'inprocess', 'stdio', or unset.

What it means

When resolving the default runtime connection, CopilotClient reads the DEFAULT_CONNECTION_ENV_VAR environment variable. If it is set to anything other than 'inprocess' or 'stdio' (case-insensitive), resolveDefaultConnection throws IllegalArgumentException, because the library will not guess what an unknown value means.

Solutions

1. Set the env var to exactly 'inprocess' or 'stdio' (case-insensitive)
2. Unset/delete the env var to fall back to option-based inference
3. Fix typos and strip surrounding whitespace/quotes in the environment

Example fix

// before
export COPILOT_DEFAULT_CONNECTION=stdio-tcp
// after
export COPILOT_DEFAULT_CONNECTION=stdio

String v = System.getenv(DEFAULT_CONNECTION_ENV_VAR);
if (v != null && !v.isBlank() && !v.trim().equalsIgnoreCase("inprocess") && !v.trim().equalsIgnoreCase("stdio")) throw new IllegalStateException("Invalid " + DEFAULT_CONNECTION_ENV_VAR + ": " + v);

try { client.resolveDefaultConnection(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Expected 'inprocess', 'stdio'")) { /* clear or fix env var */ } else throw e; }

When it happens

Trigger: Environment variable (e.g. in shell profile, CI config, container env) set to a typo like 'in-process', 'STDIO ', 'tcp', or any other string before creating a CopilotClient.

Common situations: Typos in deployment scripts or Dockerfiles; YAML/JSON configs where a different variable leaked into this env var; trailing whitespace or quotes copied into the value.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• CliUrl is mutually exclusive with CliPath
• TcpConnectionToken must be a non-empty string
• UriRuntimeConnection url must be a non-empty string
• sessionFs.initialCwd is required
• sessionFs.sessionStatePath is required

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

Appendix: source

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

        if (envValue != null && !envValue.isEmpty()) {
            if ("inprocess".equalsIgnoreCase(envValue)) {
                // Explicit subprocess options take precedence over the env var default.
                if (options.getCliUrl() != null && !options.getCliUrl().isEmpty()) {
                    return inferConnectionFromOptions(options);
                }
                if (options.getCliPath() != null && !options.getCliPath().isEmpty()) {
                    return inferConnectionFromOptions(options);
                }
                if (options.getPort() != 0) {
                    return inferConnectionFromOptions(options);
                }
                if (!options.isUseStdio() || options.getTcpConnectionToken() != null) {
                    return inferConnectionFromOptions(options);
                }
                return RuntimeConnection.forInProcess();
            }
            if (!"stdio".equalsIgnoreCase(envValue)) {
                throw new IllegalArgumentException("Invalid " + DEFAULT_CONNECTION_ENV_VAR + " value '" + envValue
                        + "'. Expected 'inprocess', 'stdio', or unset.");
            }
        }

        return inferConnectionFromOptions(options);
    }

    /**
     * Maps the individual transport options onto the equivalent
     * {@link RuntimeConnection}, preserving the behavior of clients written before
     * connections existed.
     */
    private static RuntimeConnection inferConnectionFromOptions(CopilotClientOptions options) {
        String cliUrl = options.getCliUrl();
        List<String> args = options.getCliArgs() != null ? Arrays.asList(options.getCliArgs()) : null;
        if (cliUrl != null && !cliUrl.isEmpty()) {
            return RuntimeConnection.forUri(cliUrl).setConnectionToken(options.getTcpConnectionToken());
        }

View on GitHub (pinned to cd8cf15dc3)