failed to extract runtime wrapper compatibility entrypoint

Error message

failed to extract runtime wrapper compatibility entrypoint: %w

What it means

After checksum validation, downloadCLIBinary extracts the runtime wrapper binary from package/prebuilds/<platform>/ inside the tarball. If extractFileFromTarball fails (entry missing, tar read error, or write failure), this error wraps it. It indicates the release package did not contain the expected platform-specific entrypoint.

Solutions

List the tarball contents (tar -tzf <tarball>) and confirm package/prebuilds/<platform>/<wrapperName> exists.
Verify the detected runtimePlatform is supported by the release; update bundler platform mapping if needed.
Re-download the tarball in case of corruption (checksum passed implies unlikely).
Update the bundler to a version matching the release package layout.

Example fix

// before: platform dir name mismatch
"package/prebuilds/" + runtimePlatform + "/" + wrapperName

// after: normalize platform identifier to the release's naming scheme
releasePlatform := normalizeToReleasePlatform(runtimePlatform) // e.g. "darwin-arm64"
"package/prebuilds/" + releasePlatform + "/" + wrapperName

Defensive patterns

Strategy: validation

Validate before calling

// confirm the platform entry exists before extraction
entries := listTarballEntries(tarballPath)
want := "package/prebuilds/" + runtimePlatform + "/" + wrapperName
if !slices.Contains(entries, want) {
    return fmt.Errorf("release lacks %s; supported: %v", want, filterPrefix(entries, "package/prebuilds/"))
}

Try / catch

if _, _, err := downloadCLIBinary(...); err != nil {
    if strings.Contains(err.Error(), "compatibility entrypoint") {
        return fmt.Errorf("platform %s unsupported by this release: %w", runtimePlatform, err)
    }
    return err
}

Prevention

Keep the runtimePlatform naming map in sync with the release's prebuilds folder names.
Run `tar -tzf` against a fresh release to confirm expected layout before pinning versions.
Update bundler when release packaging layout changes.
Restrict supported-platform lists to assets actually shipped.

When it happens

Trigger: extractFileFromTarball(tarballPath, destDir, "package/prebuilds/"+runtimePlatform+"/"+wrapperName, binaryName) returns an error — e.g. the tar has no entry at that exact path for the detected platform.

Common situations: Unsupported/new runtime platform whose prebuild folder is absent from the release; release packaging change renaming the prebuilds layout; partially extracted tarball; wrong GOOS/GOARCH detection mapping to a non-existent folder.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at go/cmd/bundler/main.go:1049

			assetName,
			expectedChecksum,
			actualChecksum,
		)
	}

	// The SDK release package intentionally omits the legacy SEA binary. Preserve
	// embeddedcli.Path compatibility by installing the runtime wrapper under the
	// historical copilot[.exe] name; the normal client path uses the adjacent
	// wrapper/runtime.node pair directly.
	binaryPath := filepath.Join(destDir, binaryName)
	wrapperName := runtimeWrapperName(binaryName)
	if err := extractFileFromTarball(
		tarballPath,
		destDir,
		"package/prebuilds/"+runtimePlatform+"/"+wrapperName,
		binaryName,
	); err != nil {
		return "", "", fmt.Errorf("failed to extract runtime wrapper compatibility entrypoint: %w", err)
	}

	// Verify binary exists
	if _, err := os.Stat(binaryPath); err != nil {
		return "", "", fmt.Errorf("binary not found after extraction: %w", err)
	}

	// Make executable on Unix
	if !strings.HasSuffix(binaryName, ".exe") {
		if err := os.Chmod(binaryPath, 0755); err != nil {
			return "", "", fmt.Errorf("failed to chmod binary: %w", err)
		}
	}

	stat, err := os.Stat(binaryPath)
	if err != nil {
		return "", "", fmt.Errorf("failed to stat binary: %w", err)
	}

View on GitHub (pinned to cd8cf15dc3)