BoundaryML/baml · error

%w (library or dependency not found)

Error message

%w (library or dependency not found)

What it means

If dlerror() contains "image not found" (macOS) or "no such file or directory" (Linux), loadLibrary appends "(library or dependency not found)". The library itself or one of its transitive dependencies could not be located by the loader.

Source

Thrown at engine/language_client_go/baml_go/lib_unix.go:40

// loadLibrary loads the shared library using dlopen
func loadLibrary(path string) (unsafe.Pointer, error) {
	cPath := C.CString(path)
	defer C.free(unsafe.Pointer(cPath))

	handle := C.dlopen(cPath, C.RTLD_LAZY|C.RTLD_LOCAL)
	if handle == nil {
		dlErrStr := C.GoString(C.dlerror())
		dlopenErr := fmt.Errorf("dlopen error for %s: %s", path, dlErrStr)
		if strings.Contains(dlErrStr, "mach-o, but wrong architecture") || strings.Contains(dlErrStr, "wrong ELF class") {
			dlopenErr = fmt.Errorf("%w (architecture mismatch)", dlopenErr)
		} else if strings.Contains(dlErrStr, "cannot open shared object file") {
			if strings.Contains(dlErrStr, "Permission denied") {
				dlopenErr = fmt.Errorf("%w (permission denied)", dlopenErr)
			} else {
				dlopenErr = fmt.Errorf("%w (file not found or inaccessible)", dlopenErr)
			}
		} else if strings.Contains(dlErrStr, "image not found") || strings.Contains(dlErrStr, "no such file or directory") {
			dlopenErr = fmt.Errorf("%w (library or dependency not found)", dlopenErr)
		}
		return nil, dlopenErr
	}
	return handle, nil
}

// getSymbol retrieves a symbol from the loaded library
func getSymbol(handle unsafe.Pointer, name string) (unsafe.Pointer, error) {
	if handle == nil {
		return nil, fmt.Errorf("library handle is nil when looking up symbol '%s'", name)
	}

	cName := C.CString(name)
	defer C.free(unsafe.Pointer(cName))

	C.dlerror() // Clear any existing error
	symbol := C.dlsym(handle, cName)
	errStr := C.GoString(C.dlerror())

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. On macOS run `otool -L <path>` and install/fix the listed missing dependency (e.g. via brew)
  2. On Linux run `ldd <path>` and install the missing shared object
  3. Re-download the native library to restore a deleted artifact
  4. In slim containers, add the required runtime packages (e.g. libgcc, glibc compat) to the image

Example fix

// before (docker slim image)
FROM golang:1.22-alpine   # missing glibc deps -> "no such file or directory"
// after
FROM golang:1.22-bookworm  # or: apk add libc6-compat
Defensive patterns

Strategy: validation

Validate before calling

cmd := exec.Command("ldd", libPath) // otool -L on darwin
out, err := cmd.Output()
if err != nil || strings.Contains(string(out), "not found") {
    return fmt.Errorf("missing dependency for %s", libPath)
}

Try / catch

if err := loadLibrary(path); err != nil {
    if strings.Contains(err.Error(), "library or dependency not found") {
        // run ldd/otool, install the missing dependency, retry
        return installDepsAndRetry(path)
    }
    return err
}

Prevention

When it happens

Trigger: dlopen fails with ENOENT-style errors: the .dylib/.so path is wrong, or a dependent shared library referenced by the artifact is absent (common macOS "image not found").

Common situations: Homebrew/dependency version changes changing install_name paths; missing system libraries in slim Docker images; macOS dylib expecting an @rpath that isn't set.

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

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