BoundaryML/baml · error

ErrDownloadFailed

ErrDownloadFailed

Error message

baml: failed to download shared library

What it means

ErrDownloadFailed is the sentinel for any failure while downloading the BAML native shared library: constructing the HTTP GET request, executing it (network/DNS/TLS errors), or receiving a non-success HTTP status. downloadBamlLibrary wraps all of these with %w so errors.Is(err, ErrDownloadFailed) matches.

Source

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

		Timeout:   5 * time.Minute,
	}
}

// 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

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check network egress / proxy settings; set HTTPS_PROXY if the environment requires it
2. Pre-download the library once and place it in the cache directory so no runtime download is needed
3. Read the wrapped message for the URL and underlying net/http error; test the URL with curl
4. Vendor the library into your artifact (or use a build step) to remove the runtime download dependency

Example fix

// before
// air-gapped CI: download fails at runtime
// after (CI step)
RUN curl -fL -o /root/.cache/baml/libbaml.so <pinned-release-url> && echo "$SHA256  /root/.cache/baml/libbaml.so" | sha256sum -c -

conn, err := net.DialTimeout("tcp", "github.com:443", 3*time.Second)
if err != nil {
    return fmt.Errorf("no egress for baml library download: %w", err)
}
conn.Close()

if errors.Is(err, baml.ErrDownloadFailed) {
    // use pre-vendored library from image, or retry with backoff
    return loadVendoredLibrary()
}

When it happens

Trigger: downloadBamlLibrary: http.NewRequest fails (malformed download URL), httpClient.Do returns a network error (lib_common.go:494/504), or the response status is not 200.

Common situations: Air-gapped or firewalled CI with no egress to the BAML release host; corporate proxy requiring auth; DNS failures in containers; GitHub/release CDN outage; rate limiting from repeated downloads.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Failed to download asset: {e}
• Auth server returned {status}: {body}
• PostHog returned {status}
• {err}
• network error fetching {url}: {source}

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