managed Copilot runtime unavailable: the embedded bundle…

Error message

managed Copilot runtime unavailable: the embedded bundle does not contain copilot-runtime and adjacent runtime.node; regenerate the bundle, provide an explicit path, or set COPILOT_CLI_PATH

What it means

resolveRuntimeExecutable could not locate the managed Copilot runtime: no explicit path was provided and the embedded bundle contains no copilot-runtime/runtime.node pair. The binary build lacks the managed runtime assets, so the CLI server process cannot be started.

Solutions

Set the COPILOT_CLI_PATH environment variable to a compatible runtime package path
Pass an explicit runtime executable path in the client options
Rebuild/re-embed the bundle so it contains copilot-runtime and the adjacent runtime.node (run the bundle regeneration tooling)

Example fix

// before
cmd.Env = append(os.Environ()) // no COPILOT_CLI_PATH
// after
cmd.Env = append(os.Environ(), "COPILOT_CLI_PATH=/opt/copilot/copilot-runtime")

Defensive patterns

Strategy: fallback

Validate before calling

if os.Getenv("COPILOT_CLI_PATH") == "" && runtimePathOption == "" {
    if _, err := os.Stat("/opt/copilot/copilot-runtime"); err != nil {
        return fmt.Errorf("no managed copilot runtime available")
    }
}

Try / catch

path, err := resolveRuntime()
if err != nil {
    return fmt.Errorf("copilot runtime missing: %w", err)
}

Prevention

Set COPILOT_CLI_PATH in deployment images and dev shells
Verify the embedded bundle exists after every build (check copilot-runtime + runtime.node)
Pin runtime artifacts in CI builds

When it happens

Trigger: Calling NewClient/startCLIServer (or the anonymous wrapper) with no explicit runtime path configured, no COPILOT_CLI_PATH env var, and a binary built without a valid embedded bundle.

Common situations: Building from source without running the bundle-regeneration step; slim/official release builds that strip the embedded runtime; container images lacking COPILOT_CLI_PATH; the bundle was regenerated incompletely (runtime.node missing next to copilot-runtime).

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

Appendix: source

Thrown at go/client.go:350

		client.onListModels = opts.OnListModels
	}
	if opts.SessionFS != nil {
		if err := validateSessionFSConfig(opts.SessionFS); err != nil {
			panic(err.Error())
		}
	}

	client.options = opts
	validateNewClientForMode(&client.options)
	return client
}

func resolveRuntimeExecutable(explicitPath, bundledRuntimePath string) (string, error) {
	if explicitPath != "" {
		return explicitPath, nil
	}
	if bundledRuntimePath == "" {
		return "", errors.New(
			"managed Copilot runtime unavailable: the embedded bundle does not contain copilot-runtime and adjacent runtime.node; regenerate the bundle, provide an explicit path, or set COPILOT_CLI_PATH",
		)
	}
	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{}

View on GitHub (pinned to cd8cf15dc3)