{"record":{"id":"41b359da4370ace1","repo":"github/copilot-sdk","slug":"managed-copilot-runtime-unavailable-the-embedded","errorCode":null,"errorMessage":"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","messagePattern":"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","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"go/client.go","lineNumber":350,"sourceCode":"\t\tclient.onListModels = opts.OnListModels\n\t}\n\tif opts.SessionFS != nil {\n\t\tif err := validateSessionFSConfig(opts.SessionFS); err != nil {\n\t\t\tpanic(err.Error())\n\t\t}\n\t}\n\n\tclient.options = opts\n\tvalidateNewClientForMode(&client.options)\n\treturn client\n}\n\nfunc resolveRuntimeExecutable(explicitPath, bundledRuntimePath string) (string, error) {\n\tif explicitPath != \"\" {\n\t\treturn explicitPath, nil\n\t}\n\tif bundledRuntimePath == \"\" {\n\t\treturn \"\", errors.New(\n\t\t\t\"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\",\n\t\t)\n\t}\n\treturn bundledRuntimePath, nil\n}\n\nconst defaultConnectionEnvVar = \"COPILOT_SDK_DEFAULT_CONNECTION\"\n\n// resolveDefaultConnection selects the transport when no explicit connection\n// was supplied. The override is primarily used by hosts and the E2E transport\n// matrix; explicit connection options always take precedence.\nfunc resolveDefaultConnection(env []string) RuntimeConnection {\n\tvalue := getEnvValue(env, defaultConnectionEnvVar)\n\tswitch {\n\tcase value == \"\", strings.EqualFold(value, \"stdio\"):\n\t\treturn StdioConnection{}\n\tcase strings.EqualFold(value, \"inprocess\"):\n\t\treturn InProcessConnection{}","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/client.go#L332-L368","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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)"],"exampleFix":"// before\ncmd.Env = append(os.Environ()) // no COPILOT_CLI_PATH\n// after\ncmd.Env = append(os.Environ(), \"COPILOT_CLI_PATH=/opt/copilot/copilot-runtime\")","handlingStrategy":"fallback","validationCode":"if os.Getenv(\"COPILOT_CLI_PATH\") == \"\" && runtimePathOption == \"\" {\n    if _, err := os.Stat(\"/opt/copilot/copilot-runtime\"); err != nil {\n        return fmt.Errorf(\"no managed copilot runtime available\")\n    }\n}","typeGuard":null,"tryCatchPattern":"path, err := resolveRuntime()\nif err != nil {\n    return fmt.Errorf(\"copilot runtime missing: %w\", err)\n}","preventionTips":["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"],"tags":["go","runtime","bundle","environment"],"backgroundTag":"missing-env-var","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}