{"record":{"id":"62d46ecb48e08dcd","repo":"BoundaryML/baml","slug":"errversionmismatch","errorCode":"ErrVersionMismatch","errorMessage":"baml: library version mismatch","messagePattern":"baml: library version mismatch","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_common.go","lineNumber":85,"sourceCode":"\n// setOrchestrionInternalFlag tries to set DD__tracer_internal=true using reflection.\n// This field is added by Orchestrion's code transformation.\nfunc setOrchestrionInternalFlag(transport *http.Transport) {\n\t// Use reflection to set the field if it exists\n\tval := reflect.ValueOf(transport).Elem()\n\tfield := val.FieldByName(\"DD__tracer_internal\")\n\tif field.IsValid() && field.CanSet() && field.Kind() == reflect.Bool {\n\t\tfield.SetBool(true)\n\t}\n}\n\nvar (\n\tErrLoadLibrary          = errors.New(\"baml: failed loading shared library\")\n\tErrNotSupportedPlatform = errors.New(\"baml: platform not supported (only Linux and MacOS amd64/arm64)\")\n\tErrDownloadFailed       = errors.New(\"baml: failed to download shared library\")\n\tErrCacheDir             = errors.New(\"baml: failed to determine or create cache directory\")\n\tErrChecksumMismatch     = errors.New(\"baml: downloaded library checksum mismatch\")\n\tErrVersionMismatch      = errors.New(\"baml: library version mismatch\")\n\tErrInitialization       = errors.New(\"baml: initialization failed\")\n)\n\nvar (\n\tbamlSharedLibraryPath = \"\"\n\tinitErr               error\n\tinitOnce              sync.Once\n\tbamlLibHandle         unsafe.Pointer\n\tlogger                *slog.Logger\n)\n\nfunc SetSharedLibraryPath(path string) {\n\tif bamlLibHandle != nil {\n\t\tlogger.Warn(\"SetSharedLibraryPath called after BAML library was initialized. Path ignored.\", \"path\", path)\n\t\treturn\n\t}\n\tbamlSharedLibraryPath = path\n}","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_common.go#L67-L103","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n// go.mod: baml-go v0.75.0, cached libbaml.so from v0.72.0\n// after\ngo get go.baml.dev/baml-go@v0.75.0 && rm -rf ~/.cache/baml && go run .","handlingStrategy":"validation","validationCode":"libVer, err := baml.LoadedLibraryVersion()\nif err != nil || libVer != baml.ExpectedVersion {\n    os.RemoveAll(filepath.Join(cacheDir, \"baml\")) // force matching re-download\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, baml.ErrVersionMismatch) {\n    // parse both versions from the message, clear cache, re-init\n    clearBamlCache()\n    return baml.Reinitialize()\n}","preventionTips":["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"],"tags":["versioning","shared-library","initialization"],"backgroundTag":"version-mismatch","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}