What causes "baml: downloaded library checksum mismatch" in BoundaryML/baml?

Delete the cached/temp file and re-download — a single corrupted transfer is the most common cause

ErrChecksumMismatch

ErrChecksumMismatch

Error message

baml: downloaded library checksum mismatch

What it means

ErrChecksumMismatch is returned by downloadBamlLibrary when the SHA-256 of the downloaded native library does not match the pinned expected checksum. This guard exists so a corrupt or tampered download is never loaded or executed. The error names the file, expected and actual checksums.

Source

Thrown at engine/language_client_go/baml_go/lib_common.go:84

}

// setOrchestrionInternalFlag tries to set DD__tracer_internal=true using reflection.
// This field is added by Orchestrion's code transformation.
func setOrchestrionInternalFlag(transport *http.Transport) {
	// Use reflection to set the field if it exists
	val := reflect.ValueOf(transport).Elem()
	field := val.FieldByName("DD__tracer_internal")
	if field.IsValid() && field.CanSet() && field.Kind() == reflect.Bool {
		field.SetBool(true)
	}
}

var (
	ErrLoadLibrary          = errors.New("baml: failed loading shared library")
	ErrNotSupportedPlatform = errors.New("baml: platform not supported (only Linux and MacOS amd64/arm64)")
	ErrDownloadFailed       = errors.New("baml: failed to download shared library")
	ErrCacheDir             = errors.New("baml: failed to determine or create cache directory")
	ErrChecksumMismatch     = errors.New("baml: downloaded library checksum mismatch")
	ErrVersionMismatch      = errors.New("baml: library version mismatch")
	ErrInitialization       = errors.New("baml: initialization failed")
)

var (
	bamlSharedLibraryPath = ""
	initErr               error
	initOnce              sync.Once
	bamlLibHandle         unsafe.Pointer
	logger                *slog.Logger
)

func SetSharedLibraryPath(path string) {
	if bamlLibHandle != nil {
		logger.Warn("SetSharedLibraryPath called after BAML library was initialized. Path ignored.", "path", path)
		return
	}
	bamlSharedLibraryPath = path

View on GitHub (pinned to bd85ce9dee)

Solutions

Delete the cached/temp file and re-download — a single corrupted transfer is the most common cause
Verify your network path: bypass suspicious proxies or retry from a different network
Confirm the Go client VERSION matches a released library artifact; a stale pinned checksum vs newer artifact indicates a version skew
If it persists, check the release infrastructure/checksum manifest and report upstream

Example fix

// before
// flaky proxy truncated the download once; lib cached corrupt
// after
rm -rf "$HOME/.cache/baml" && go run .  // forces clean re-download and checksum verification

Defensive patterns

Strategy: retry

Validate before calling

sum, err := computeSha256(tmpFile)
if err != nil || sum == "" {
    return fmt.Errorf("download produced empty/corrupt file")
}

Try / catch

if errors.Is(err, baml.ErrChecksumMismatch) {
    os.Remove(cachedLib)
    return retryDownload(3, time.Second) // clean re-download with backoff
}

Prevention

Delete cached library files when checksum errors appear — never force-load an unverified file
Avoid TLS-intercepting proxies for release-artifact hosts
Keep client VERSION and release artifacts aligned so pinned checksums are valid

When it happens

Trigger: downloadBamlLibrary at lib_common.go:544: actualChecksum != expectedChecksum after hashing the downloaded temp file for the target platform filename.

Common situations: Interrupted/proxied downloads producing truncated files; corporate TLS-inspection proxies modifying payloads; CDN serving a stale artifact after a release; MITM tampering (the case the check defends against).

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/2c206b38bdbd6f50. Report an issue: GitHub.