BoundaryML/baml · critical

LoadLibrary failed for %s: error code %d: %w

Error message

LoadLibrary failed for %s: error code %d: %w

What it means

loadLibrary on Windows reports this error when LoadLibraryW returns a zero handle, meaning Windows could not load the BAML native DLL. The message includes the requested path, the GetLastError code, and the syscall's syscall.Errno. Typical causes are a missing DLL, a bad path, or missing dependent DLLs / architecture mismatch.

Source

Thrown at engine/language_client_go/baml_go/lib_windows.go:39

	kernel32 = syscall.NewLazyDLL("kernel32.dll")

	procLoadLibraryW   = kernel32.NewProc("LoadLibraryW")
	procGetProcAddress = kernel32.NewProc("GetProcAddress")
	procFreeLibrary    = kernel32.NewProc("FreeLibrary")
	procGetLastError   = kernel32.NewProc("GetLastError")
)

// loadLibrary loads the shared library using LoadLibrary
func loadLibrary(path string) (unsafe.Pointer, error) {
	pathPtr, err := syscall.UTF16PtrFromString(path)
	if err != nil {
		return nil, fmt.Errorf("invalid library path: %w", err)
	}

	handle, _, err := procLoadLibraryW.Call(uintptr(unsafe.Pointer(pathPtr)))
	if handle == 0 {
		lastErr, _, _ := procGetLastError.Call()
		return nil, fmt.Errorf("LoadLibrary failed for %s: error code %d: %w", path, lastErr, err)
	}

	return unsafe.Pointer(handle), nil
}

// getSymbol retrieves a symbol from the loaded library
func getSymbol(handle unsafe.Pointer, name string) (unsafe.Pointer, error) {
	namePtr, err := syscall.BytePtrFromString(name)
	if err != nil {
		return nil, fmt.Errorf("invalid symbol name: %w", err)
	}

	proc, _, err := procGetProcAddress.Call(
		uintptr(handle),
		uintptr(unsafe.Pointer(namePtr)),
	)

	if proc == 0 {

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Verify the DLL exists at the path in the error message (os.Stat) and that the process architecture matches the DLL (use `file`/dumpbin or check GOARCH).
2. Install missing dependencies of the DLL, especially the Microsoft Visual C++ Redistributable, and confirm dependent DLLs are on PATH or next to the executable.
3. Reinstall/refresh the baml Go module so the bundled native library is restored (go clean -cache + go mod download), and check antivirus quarantine logs.
4. Cross-check the Windows error code in the message (e.g. 126 = module not found, 193 = bad executable format) to pinpoint the cause.

Example fix

// before
// fails: baml.dll not shipped next to the exe
runtime.Init(filepath.Join(os.Args[0], "baml.dll"))

// after
dllPath := filepath.Join(filepath.Dir(os.Executable()), "baml.dll")
if _, err := os.Stat(dllPath); err != nil {
    return fmt.Errorf("baml native library missing: %w", err)
}
runtime.Init(dllPath)

if _, err := os.Stat(dllPath); err != nil {
    return fmt.Errorf("native library missing at %s: %w", dllPath, err)
}

func dllPresent(path string) bool {
    _, err := os.Stat(path)
    return err == nil
}

if _, err := runtimeInit(path); err != nil {
    var loadErr *runtime.LoadError
    if errors.As(err, &loadErr) {
        log.Fatalf("cannot load BAML DLL %s: %v — check arch and VC++ runtime", loadErr.Path, loadErr.Code)
    }
    return err
}

When it happens

Trigger: BAML runtime initialization on Windows where the bundled native library is absent from the expected location, the path is wrong, the DLL's own dependencies (e.g. MSVC runtime) are missing, or a 32-bit process tries to load a 64-bit DLL (or vice versa).

Common situations: Deployment that excludes the native .dll from the artifact; antivirus quarantine of the DLL; moving the executable away from the DLL directory; installing the wrong-architecture build; missing VC++ redistributables on clean machines.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• GetProcAddress failed for %s: error code %d: %w
• FreeLibrary failed: %w
• invalid library path: %w
• invalid symbol name: %w
• usage: baml --replace <tmp> <current>

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