BoundaryML/baml · error

ErrCacheDir

ErrCacheDir

Error message

baml: failed to determine or create cache directory

What it means

ErrCacheDir is returned by getCacheDir when it cannot determine the user cache directory (os.UserCacheDir fails) or cannot create the cache directory with os.MkdirAll(0755). Without a cache location the library cannot store or find the downloaded native shared library.

Source

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

	}
}

// 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. Set HOME (Linux/macOS) or XDG_CACHE_HOME to a writable directory before the process starts
2. Verify the cache parent directory is writable by the process user; chown/chmod if needed
3. Mount a writable volume at the cache path in containers (e.g. emptyDir for /root/.cache)
4. Check for read-only root filesystem or disk-full conditions in the deployment

Example fix

// before
// Dockerfile: no HOME set for the app user
// after
ENV HOME=/home/app
RUN mkdir -p /home/app/.cache && chown -R app:app /home/app

cacheDir, err := os.UserCacheDir()
if err != nil {
    os.Setenv("XDG_CACHE_HOME", "/tmp/.cache") // or fail before starting
}
if err := os.MkdirAll(filepath.Join(cacheDir, "baml"), 0o755); err != nil {
    return err
}

if errors.Is(err, baml.ErrCacheDir) {
    log.Errorf("cache dir unusable: %v", err)
    os.Exit(1) // environment misconfiguration, not retryable
}

When it happens

Trigger: getCacheDir at lib_common.go:394 when os.UserCacheDir errors (e.g. HOME and XDG_CACHE_HOME both unset on Linux), and :409 when os.MkdirAll fails (permissions, read-only filesystem, full disk).

Common situations: Docker containers or systemd services running with no HOME set; read-only root filesystems in Kubernetes; running as a user without write access to the cache path; SELinux/AppArmor denials.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• failed to install {} into {}
• access error: {message}
• failed create destination %s: %w
• IO error: {0}
• toolchain binary is not executable: {}{origin}

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