What causes "baml: library version mismatch" in BoundaryML/baml?

Delete the cached native library (os.UserCacheDir()/baml) so a matching version is re-downloaded

ErrVersionMismatch

ErrVersionMismatch

Error message

baml: library version mismatch

What it means

ErrVersionMismatch is returned by initializeBaml after loading the shared library when the library's reported BAML version does not equal the VERSION expected by the Go package. Running mismatched versions risks FFI/protobuf incompatibilities, so initialization aborts.

Source

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

// 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 native library (os.UserCacheDir()/baml) so a matching version is re-downloaded
Align versions: upgrade the native library release to match baml-go VERSION (read both versions from the error message)
In Docker, invalidate the layer that pre-copies the library when bumping baml-go
Pin exact versions of both the Go module and any manually vendored native artifact in CI

Example fix

// before
// go.mod: baml-go v0.75.0, cached libbaml.so from v0.72.0
// after
go get go.baml.dev/baml-go@v0.75.0 && rm -rf ~/.cache/baml && go run .

Defensive patterns

Strategy: validation

Validate before calling

libVer, err := baml.LoadedLibraryVersion()
if err != nil || libVer != baml.ExpectedVersion {
    os.RemoveAll(filepath.Join(cacheDir, "baml")) // force matching re-download
}

Try / catch

if errors.Is(err, baml.ErrVersionMismatch) {
    // parse both versions from the message, clear cache, re-init
    clearBamlCache()
    return baml.Reinitialize()
}

Prevention

Bump baml-go and clear the baml cache directory in the same deploy step
In Docker, COPY the library in a layer keyed to the baml-go version
Record and assert both versions in a startup health check

When it happens

Trigger: initializeBaml at lib_common.go:176: goVersionStr loaded from the native library differs from the Go package's VERSION constant; bamlLibHandle is released and init fails.

Common situations: Upgrading baml-go via go get without clearing the previously downloaded cached library; pinning the native library manually to an old release; stale Docker layer containing an older .so.

Related errors

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