What causes "invalid library path: %w" in BoundaryML/baml?

Sanitize the library path: strip everything from the first NUL byte before passing it to the runtime (strings.SplitN(path, "\x00", 2)[0]).

BoundaryML/baml · error

invalid library path: %w

Error message

invalid library path: %w

What it means

loadLibrary on Windows converts the shared-library path to a UTF-16 pointer via syscall.UTF16PtrFromString before calling LoadLibraryW. This error is returned when that conversion fails, which happens only for paths containing NUL (0x00) bytes — the Windows API cannot accept embedded nulls. It wraps the original syscall error.

Source

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

	"fmt"
	"syscall"
	"unsafe"
)

var (
	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)
	}

View on GitHub (pinned to bd85ce9dee)

Solutions

Sanitize the library path: strip everything from the first NUL byte before passing it to the runtime (strings.SplitN(path, "\x00", 2)[0]).
Check where the path originates (config file, env var) and fix the producer that is emitting embedded nulls.
Validate the path with strings.ContainsRune(path, 0) before initializing the BAML runtime.
Re-encode the path from its source (e.g. re-read env var with os.Getenv) to remove corruption.

Example fix

// before
runtime.Init(path) // path contains "C:\\libs\\baml.dll\x00junk"

// after
cleanPath := strings.SplitN(path, "\x00", 2)[0]
if strings.ContainsRune(cleanPath, 0) {
    return fmt.Errorf("path still contains NUL")
}
runtime.Init(cleanPath)

Defensive patterns

Strategy: validation

Validate before calling

if strings.ContainsRune(path, 0) {
    return fmt.Errorf("library path contains NUL byte: %q", path)
}

Type guard

func validLibPath(p string) bool {
    return p != "" && !strings.ContainsRune(p, 0)
}

Try / catch

if _, err := syscall.UTF16PtrFromString(path); err != nil {
    return fmt.Errorf("bad library path: %w", err)
}

Prevention

Trim NUL terminators when paths come from binary buffers or C interop.
Validate library paths with os.Stat before runtime initialization.
Keep paths as plain Go strings from trusted sources (os.Getenv, flags).

When it happens

Trigger: Calling loadLibrary (indirectly via BAML runtime initialization) with a library path string containing a NUL character, e.g. a path built from a zero-terminated buffer or truncated string.

Common situations: Paths read from binary config or environment buffers without trimming at the terminator; path manipulation that appends "\x00"; corrupted configuration values where a null byte snuck into the DLL location.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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