{"record":{"id":"bf662455ed19d509","repo":"github/copilot-sdk","slug":"no-runtime-version-is-pinned","errorCode":null,"errorMessage":"No runtime version is pinned.","messagePattern":"No runtime version is pinned\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/_cli_download.py","lineNumber":325,"sourceCode":"            if relative is None or member.isdir():\n                continue\n            if not member.isfile():\n                raise RuntimeError(f\"Unsupported runtime package entry: {member.name}\")\n            extracted = archive.extractfile(member)\n            if extracted is None:\n                raise RuntimeError(f\"Failed to read runtime package entry: {member.name}\")\n            target = destination / relative\n            target.parent.mkdir(parents=True, exist_ok=True)\n            target.write_bytes(extracted.read())\n            if sys.platform != \"win32\":\n                target.chmod(member.mode & 0o777)\n\n\ndef ensure_runtime_wrapper(version: str | None = None, force: bool = False) -> str:\n    \"\"\"Provision the runtime pair and retained assets from the release package.\"\"\"\n    ver = version or CLI_VERSION\n    if not ver:\n        raise RuntimeError(\"No runtime version is pinned.\")\n    runtime_platform = get_runtime_platform()\n    wrapper_name = \"copilot-runtime.exe\" if sys.platform == \"win32\" else \"copilot-runtime\"\n    pair_dir = get_cache_dir(ver) / \"prebuilds\" / runtime_platform\n    wrapper_path = pair_dir / wrapper_name\n    runtime_path = pair_dir / \"runtime.node\"\n    assets_marker = pair_dir / _HOSTLESS_ASSETS_MARKER\n\n    wrapper_exists = wrapper_path.is_file() and wrapper_path.stat().st_size > 0\n    runtime_exists = runtime_path.is_file() and runtime_path.stat().st_size > 0\n    if _runtime_bundle_is_complete(pair_dir, wrapper_name) and not force:\n        return str(wrapper_path)\n    if not force and wrapper_exists != runtime_exists:\n        raise RuntimeError(\n            f\"Incomplete Copilot runtime bundle in {pair_dir}: \"\n            f\"{wrapper_name} and runtime.node are required.\"\n        )\n    if _should_skip_download():\n        raise RuntimeError(","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/_cli_download.py#L307-L343","documentation":"ensure_runtime_wrapper provisions the Copilot runtime pair from a release package and needs a pinned version. Like download_cli, it refuses to run with an unpinned CLI_VERSION (development install) and raises this error.","triggerScenarios":"Calling ensure_runtime_wrapper(), or any caller that reaches it (download_cli, ensure_runtime_library, main, _resolve_runtime_entrypoint, _resolve_inprocess_runtime), with no version argument while CLI_VERSION is empty.","commonSituations":"Running from a source/editable install where CLI_VERSION was never stamped; forgetting to set COPILOT_CLI_PATH in dev environments.","solutions":["Install a published wheel that embeds CLI_VERSION.","Set COPILOT_CLI_PATH to an existing runtime/CLI binary.","Pass version=<release> explicitly to ensure_runtime_wrapper.","Rebuild the package so the version stamping step runs."],"exampleFix":"# before\nensure_runtime_wrapper()  # dev install, CLI_VERSION empty\n# after\nensure_runtime_wrapper(version=\"0.2.1\")\n# or set COPILOT_CLI_PATH","handlingStrategy":"validation","validationCode":"import copilot._cli_download as d\nif not (d.CLI_VERSION or os.environ.get(\"COPILOT_CLI_PATH\")):\n    raise SystemExit(\"pin a runtime version or set COPILOT_CLI_PATH\")","typeGuard":null,"tryCatchPattern":"try:\n    wrapper = ensure_runtime_wrapper()\nexcept RuntimeError as e:\n    if \"No runtime version is pinned\" in str(e):\n        wrapper = os.environ[\"COPILOT_CLI_PATH\"]\n    else:\n        raise","preventionTips":["Install published wheels, not source trees, in deployment.","Pass explicit versions when calling provisioning APIs programmatically.","Fail fast at startup if CLI_VERSION is empty and no COPILOT_CLI_PATH is set."],"tags":["configuration","missing-version","development-install"],"backgroundTag":"missing-config-value","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}