What causes "invalid %s value %q: expected "inprocess", "stdio", or unset" in github/copilot-sdk?

Set the env var to exactly "stdio" or "inprocess" (case-insensitive), or unset it entirely.

invalid value : expected "inprocess", "stdio", or unset

Error message

invalid %s value %q: expected "inprocess", "stdio", or unset

What it means

resolveDefaultConnection panics when the default-connection environment variable (defaultConnectionEnvVar, e.g. controlling COPILOT_CLI_CONNECTION) holds a value other than "inprocess", "stdio", or empty. The env var selects the transport used when none is given in code, and only those two transports exist.

Solutions

Set the env var to exactly "stdio" or "inprocess" (case-insensitive), or unset it entirely.
Pass an explicit Connection in code (StdioConnection{} or InProcessConnection{}) so the env var is ignored.
Grep your deploy scripts/CI for the env var name and fix stale values after SDK upgrades.

Example fix

// before (shell)
export COPILOT_CLI_CONNECTION=in-process
// after (shell)
export COPILOT_CLI_CONNECTION=inprocess
// or in Go, override explicitly:
client := clientpkg.NewClient(&clientpkg.Options{Connection: clientpkg.InProcessConnection{}})

Defensive patterns

Strategy: validation

Validate before calling

switch strings.ToLower(os.Getenv("COPILOT_CLI_CONNECTION")) {
case "", "stdio", "inprocess":
    // ok
default:
    return fmt.Errorf("invalid COPILOT_CLI_CONNECTION value %q", os.Getenv("COPILOT_CLI_CONNECTION"))
}

Prevention

Validate the env var at process startup, before any client construction.
Prefer setting Connection explicitly in code over relying on the env var.
Use an allowlist check (case-insensitive) in shell scripts and CI.

When it happens

Trigger: Setting the env var to a typo or unsupported transport name (e.g. "in-process", "tcp", "child") and then calling NewClient without an explicit Connection. Panic raised at go/client.go:370 with the offending value.

Common situations: CI/export scripts exporting COPILOT_CLI_CONNECTION=in-process (hyphen) instead of inprocess; documentation drift after the env var was introduced; shell typos.

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

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

Appendix: source

Thrown at go/client.go:370

		)
	}
	return bundledRuntimePath, nil
}

const defaultConnectionEnvVar = "COPILOT_SDK_DEFAULT_CONNECTION"

// resolveDefaultConnection selects the transport when no explicit connection
// was supplied. The override is primarily used by hosts and the E2E transport
// matrix; explicit connection options always take precedence.
func resolveDefaultConnection(env []string) RuntimeConnection {
	value := getEnvValue(env, defaultConnectionEnvVar)
	switch {
	case value == "", strings.EqualFold(value, "stdio"):
		return StdioConnection{}
	case strings.EqualFold(value, "inprocess"):
		return InProcessConnection{}
	default:
		panic(fmt.Sprintf(
			"invalid %s value %q: expected \"inprocess\", \"stdio\", or unset",
			defaultConnectionEnvVar,
			value,
		))
	}
}

// getEnvValue looks up a key in an environment slice ([]string of "KEY=VALUE").
// Returns the value if found, or empty string otherwise.
func getEnvValue(env []string, key string) string {
	prefix := key + "="
	for i := len(env) - 1; i >= 0; i-- {
		if strings.HasPrefix(env[i], prefix) {
			return env[i][len(prefix):]
		}
	}
	return ""
}

View on GitHub (pinned to cd8cf15dc3)