{"record":{"id":"61ff2edb21b402e1","repo":"BoundaryML/baml","slug":"errcachedir","errorCode":"ErrCacheDir","errorMessage":"baml: failed to determine or create cache directory","messagePattern":"baml: failed to determine or create cache directory","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_common.go","lineNumber":83,"sourceCode":"\t}\n}\n\n// setOrchestrionInternalFlag tries to set DD__tracer_internal=true using reflection.\n// This field is added by Orchestrion's code transformation.\nfunc setOrchestrionInternalFlag(transport *http.Transport) {\n\t// Use reflection to set the field if it exists\n\tval := reflect.ValueOf(transport).Elem()\n\tfield := val.FieldByName(\"DD__tracer_internal\")\n\tif field.IsValid() && field.CanSet() && field.Kind() == reflect.Bool {\n\t\tfield.SetBool(true)\n\t}\n}\n\nvar (\n\tErrLoadLibrary          = errors.New(\"baml: failed loading shared library\")\n\tErrNotSupportedPlatform = errors.New(\"baml: platform not supported (only Linux and MacOS amd64/arm64)\")\n\tErrDownloadFailed       = errors.New(\"baml: failed to download shared library\")\n\tErrCacheDir             = errors.New(\"baml: failed to determine or create cache directory\")\n\tErrChecksumMismatch     = errors.New(\"baml: downloaded library checksum mismatch\")\n\tErrVersionMismatch      = errors.New(\"baml: library version mismatch\")\n\tErrInitialization       = errors.New(\"baml: initialization failed\")\n)\n\nvar (\n\tbamlSharedLibraryPath = \"\"\n\tinitErr               error\n\tinitOnce              sync.Once\n\tbamlLibHandle         unsafe.Pointer\n\tlogger                *slog.Logger\n)\n\nfunc SetSharedLibraryPath(path string) {\n\tif bamlLibHandle != nil {\n\t\tlogger.Warn(\"SetSharedLibraryPath called after BAML library was initialized. Path ignored.\", \"path\", path)\n\t\treturn\n\t}","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_common.go#L65-L101","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Set HOME (Linux/macOS) or XDG_CACHE_HOME to a writable directory before the process starts","Verify the cache parent directory is writable by the process user; chown/chmod if needed","Mount a writable volume at the cache path in containers (e.g. emptyDir for /root/.cache)","Check for read-only root filesystem or disk-full conditions in the deployment"],"exampleFix":"// before\n// Dockerfile: no HOME set for the app user\n// after\nENV HOME=/home/app\nRUN mkdir -p /home/app/.cache && chown -R app:app /home/app","handlingStrategy":"validation","validationCode":"cacheDir, err := os.UserCacheDir()\nif err != nil {\n    os.Setenv(\"XDG_CACHE_HOME\", \"/tmp/.cache\") // or fail before starting\n}\nif err := os.MkdirAll(filepath.Join(cacheDir, \"baml\"), 0o755); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, baml.ErrCacheDir) {\n    log.Errorf(\"cache dir unusable: %v\", err)\n    os.Exit(1) // environment misconfiguration, not retryable\n}","preventionTips":["Always set HOME or XDG_CACHE_HOME in containers and systemd units","Mount a writable volume at the cache path in read-only-root deployments","Pre-create the cache directory with correct ownership in entrypoint scripts"],"tags":["filesystem","cache","permissions"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}