{"record":{"id":"219b339817377bf7","repo":"github/copilot-sdk","slug":"invalid-default-connection-env-var-value-env","errorCode":null,"errorMessage":"Invalid ${DEFAULT_CONNECTION_ENV_VAR} value '${envValue}'. Expected 'inprocess', 'stdio', or unset.","messagePattern":"Invalid (.+?) value '(.+?)'\\. Expected 'inprocess', 'stdio', or unset\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":283,"sourceCode":"        if (envValue != null && !envValue.isEmpty()) {\n            if (\"inprocess\".equalsIgnoreCase(envValue)) {\n                // Explicit subprocess options take precedence over the env var default.\n                if (options.getCliUrl() != null && !options.getCliUrl().isEmpty()) {\n                    return inferConnectionFromOptions(options);\n                }\n                if (options.getCliPath() != null && !options.getCliPath().isEmpty()) {\n                    return inferConnectionFromOptions(options);\n                }\n                if (options.getPort() != 0) {\n                    return inferConnectionFromOptions(options);\n                }\n                if (!options.isUseStdio() || options.getTcpConnectionToken() != null) {\n                    return inferConnectionFromOptions(options);\n                }\n                return RuntimeConnection.forInProcess();\n            }\n            if (!\"stdio\".equalsIgnoreCase(envValue)) {\n                throw new IllegalArgumentException(\"Invalid \" + DEFAULT_CONNECTION_ENV_VAR + \" value '\" + envValue\n                        + \"'. Expected 'inprocess', 'stdio', or unset.\");\n            }\n        }\n\n        return inferConnectionFromOptions(options);\n    }\n\n    /**\n     * Maps the individual transport options onto the equivalent\n     * {@link RuntimeConnection}, preserving the behavior of clients written before\n     * connections existed.\n     */\n    private static RuntimeConnection inferConnectionFromOptions(CopilotClientOptions options) {\n        String cliUrl = options.getCliUrl();\n        List<String> args = options.getCliArgs() != null ? Arrays.asList(options.getCliArgs()) : null;\n        if (cliUrl != null && !cliUrl.isEmpty()) {\n            return RuntimeConnection.forUri(cliUrl).setConnectionToken(options.getTcpConnectionToken());\n        }","sourceCodeStart":265,"sourceCodeEnd":301,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L265-L301","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the env var to exactly 'inprocess' or 'stdio' (case-insensitive)","Unset/delete the env var to fall back to option-based inference","Fix typos and strip surrounding whitespace/quotes in the environment"],"exampleFix":"// before\nexport COPILOT_DEFAULT_CONNECTION=stdio-tcp\n// after\nexport COPILOT_DEFAULT_CONNECTION=stdio","handlingStrategy":"validation","validationCode":"String v = System.getenv(DEFAULT_CONNECTION_ENV_VAR);\nif (v != null && !v.isBlank() && !v.trim().equalsIgnoreCase(\"inprocess\") && !v.trim().equalsIgnoreCase(\"stdio\")) throw new IllegalStateException(\"Invalid \" + DEFAULT_CONNECTION_ENV_VAR + \": \" + v);","typeGuard":null,"tryCatchPattern":"try { client.resolveDefaultConnection(options); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"Expected 'inprocess', 'stdio'\")) { /* clear or fix env var */ } else throw e; }","preventionTips":["Only set the env var to 'inprocess' or 'stdio'","Validate the value at deployment/CI time","Avoid setting it in shared base images"],"tags":["java","environment-variable","configuration","validation"],"backgroundTag":"invalid-env-var-value","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"}