in-process runtime unavailable: build with the bundled…

Error message

in-process runtime unavailable: build with the bundled embedded runtime or set COPILOT_CLI_PATH to a compatible runtime package

What it means

startInProcess found no runtime library to load: no explicit entrypoint was configured, no COPILOT_CLI_PATH was set, and embeddedcli.RuntimePath() returned empty (no bundled embedded runtime in this build). The in-process host cannot be created without a runtime path.

Solutions

Set COPILOT_CLI_PATH to a compatible runtime package directory
Build with the bundled embedded runtime so embeddedcli.RuntimePath() is non-empty
Pass an explicit runtime path through the client options

Example fix

// before
os.Unsetenv("COPILOT_CLI_PATH")
// after
os.Setenv("COPILOT_CLI_PATH", "/opt/copilot/runtime")

Defensive patterns

Strategy: fallback

Validate before calling

if os.Getenv("COPILOT_CLI_PATH") == "" && embeddedcli.RuntimePath() == "" {
    return fmt.Errorf("no in-process runtime available")
}

Try / catch

if err := client.StartInProcess(ctx); err != nil && strings.Contains(err.Error(), "runtime unavailable") {
    os.Setenv("COPILOT_CLI_PATH", runtimePath)
    return client.StartInProcess(ctx)
}

Prevention

Ship a build with the embedded runtime or always set COPILOT_CLI_PATH
Avoid env sanitization that strips COPILOT_CLI_PATH in services
Check runtimePath availability before selecting in-process mode

When it happens

Trigger: Calling startInProcess with an empty cliPath, unset COPILOT_CLI_PATH, and a build without the embedded runtime bundle.

Common situations: Custom builds that did not embed the runtime; running from a workspace without the bundled runtime files; environments where COPILOT_CLI_PATH is stripped (sanitized env in services/containers).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at go/client.go:2273

}

// startInProcess loads the native runtime library and wires the JSON-RPC client
// to its FFI byte streams.
func (c *Client) startInProcess(ctx context.Context) error {
	if !inProcessAvailable {
		return errors.New("in-process transport unavailable: rebuild with -tags copilot_inprocess on a supported platform")
	}

	cliEntrypoint := c.cliPath
	if cliEntrypoint == "" {
		cliEntrypoint = getEnvValue(c.options.Env, "COPILOT_CLI_PATH")
	}
	runtimePath := cliEntrypoint
	if runtimePath == "" {
		runtimePath = embeddedcli.RuntimePath()
	}
	if runtimePath == "" {
		return errors.New("in-process runtime unavailable: build with the bundled embedded runtime or set COPILOT_CLI_PATH to a compatible runtime package")
	}

	config := c.inProcessHostConfig()

	host, err := createInProcessHost(runtimePath, cliEntrypoint, config)
	if err != nil {
		return err
	}
	// Own the host before the blocking handshake so a cancelled or failed start
	// leaves it disposable by Stop/ForceStop rather than leaking (host.Start runs
	// on its own goroutine and cannot be interrupted once the native call begins).
	c.ffiHost = host

	errCh := make(chan error, 1)
	go func() { errCh <- host.Start() }()
	select {
	case err := <-errCh:
		if err != nil {

View on GitHub (pinned to cd8cf15dc3)