LinuxMuslRuntimeLibHash must be a SHA-256 hash

Error message

LinuxMuslRuntimeLibHash must be a SHA-256 hash (%d bytes), got %d bytes

What it means

If Config.LinuxMuslRuntimeLib is supplied, Setup validates that LinuxMuslRuntimeLibHash is exactly sha256.Size (32) bytes and panics otherwise. The runtime library, like other optional assets, must carry a correct-length SHA-256 checksum for integrity verification during install.

Solutions

Assign the raw 32-byte sha256.Sum256 output of the runtime library to LinuxMuslRuntimeLibHash
Hex-decode the digest with hex.DecodeString if you only have the hex form
Ensure the hash corresponds to the same bytes passed as LinuxMuslRuntimeLib
Add a length assertion before calling Setup

Example fix

// before
Setup(Config{LinuxMuslRuntimeLib: libReader, LinuxMuslRuntimeLibHash: []byte(hexSum)})
// after
raw, _ := hex.DecodeString(hexSum)
Setup(Config{LinuxMuslRuntimeLib: libReader, LinuxMuslRuntimeLibHash: raw})

Defensive patterns

Strategy: validation

Validate before calling

if linuxMuslRuntimeLib != nil && len(linuxMuslRuntimeLibHash) != sha256.Size {
	return errors.New("LinuxMuslRuntimeLibHash must be raw 32-byte SHA-256")
}

Prevention

Use sha256.Sum256 on the exact embedded library bytes
Decode hex digests before assignment
Review Config literals for all LinuxMusl* hash fields when adding assets
Validate the whole Config with a helper before Setup

When it happens

Trigger: Calling Setup with a non-nil LinuxMuslRuntimeLib while LinuxMuslRuntimeLibHash is nil, empty, hex-encoded-as-bytes, or a digest of the wrong length/algorithm.

Common situations: Wiring a new musl runtime library into the embed config without generating its hash, copying a hash from a different asset, or passing hex text instead of decoded raw bytes.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at go/internal/embeddedcli/embeddedcli.go:76

	LinuxMuslRuntimeAssets         io.Reader
	LinuxMuslRuntimeAssetsHash     []byte

	Dir     string
	Version string
}

func Setup(cfg Config) {
	if cfg.Cli == nil {
		panic("Cli reader is required")
	}
	if len(cfg.CliHash) != sha256.Size {
		panic(fmt.Sprintf("CliHash must be a SHA-256 hash (%d bytes), got %d bytes", sha256.Size, len(cfg.CliHash)))
	}
	if cfg.LinuxMuslCli != nil && len(cfg.LinuxMuslCliHash) != sha256.Size {
		panic(fmt.Sprintf("LinuxMuslCliHash must be a SHA-256 hash (%d bytes), got %d bytes", sha256.Size, len(cfg.LinuxMuslCliHash)))
	}
	if cfg.LinuxMuslRuntimeLib != nil && len(cfg.LinuxMuslRuntimeLibHash) != sha256.Size {
		panic(fmt.Sprintf("LinuxMuslRuntimeLibHash must be a SHA-256 hash (%d bytes), got %d bytes", sha256.Size, len(cfg.LinuxMuslRuntimeLibHash)))
	}
	validateRuntimePairConfig(cfg.RuntimeExecutable, cfg.RuntimeExecutableHash, cfg.RuntimeNode, cfg.RuntimeNodeHash, "")
	validateRuntimePairConfig(cfg.LinuxMuslRuntimeExecutable, cfg.LinuxMuslRuntimeExecutableHash, cfg.LinuxMuslRuntimeNode, cfg.LinuxMuslRuntimeNodeHash, "LinuxMusl")
	validateOptionalHash(cfg.RuntimeAssets, cfg.RuntimeAssetsHash, "RuntimeAssetsHash")
	validateOptionalHash(cfg.LinuxMuslRuntimeAssets, cfg.LinuxMuslRuntimeAssetsHash, "LinuxMuslRuntimeAssetsHash")
	setupMu.Lock()
	defer setupMu.Unlock()
	if setupDone {
		panic("Setup must only be called once")
	}
	if pathInitialized {
		panic("Setup must be called before Path is accessed")
	}
	config = cfg
	setupDone = true
}

var Path = sync.OnceValue(func() string {

View on GitHub (pinned to cd8cf15dc3)