When a provider is in the NotReady state, all flag evaluations will fail with FeatureFlagError.ProviderNotReady. When a provider enters the Fatal state, all flag evaluations will fail with FeatureFlagError.ProviderFatal.
Events (Spec 5.x)
Requirement
Status
Implementation
Ready event
✅
ProviderEvent.Ready
Error event
✅
ProviderEvent.Error
Stale event
✅
ProviderEvent.Stale
ConfigurationChanged
✅
ProviderEvent.ConfigurationChanged
Reconnecting event
✅
ProviderEvent.Reconnecting
Event stream
✅
FeatureFlags.events returns ZStream
Handler registration
✅
onProviderReady, onProviderError, etc.
Handler cancellation
✅
Handlers return cancellation effect
Generic handler
✅
on(eventType, handler)
Immediate execution
✅
Handlers run immediately if state matches (Spec 5.3.3)
Event Handlers
// Specific event handlers (return cancellation effect)valcancel=FeatureFlags.onProviderReady{metadata=>ZIO.logInfo(s"Provider ${metadata.name} is ready")}// Cancel when no longer neededcancel.flatMap(c=>c)// Generic event handlerFeatureFlags.on(ProviderEventType.Error,event=>ZIO.logError(s"Error: $event"))// Event streamFeatureFlags.events.foreach{event=>ZIO.logInfo(s"Event: $event")}.fork
Tracking (Spec 2.7)
Requirement
Status
Implementation
Track event name
✅
track(eventName)
Track with context
✅
track(eventName, context)
Track with details
✅
track(eventName, details)
Track full
✅
track(eventName, context, details)
Tracking Example
// Simple trackingFeatureFlags.track("button-clicked")// With contextFeatureFlags.track("purchase",EvaluationContext("user-123"))// With detailsvaldetails=TrackingEventDetails(value=Some(99.99),attributes=Map("currency"->"USD","items"->3))FeatureFlags.track("checkout",details)
ZIO-Specific Features
Beyond the OpenFeature spec, ZIO OpenFeature provides:
Feature
Description
Transactions
Scoped overrides with evaluation caching and tracking
Fiber-local context
withContext scopes context to a code block via FiberRef
Type-safe evaluation
FlagType type class for compile-time safety
Effect-based hooks
Hooks return UIO instead of callbacks
Resource management
Automatic lifecycle via ZIO Scope
Event streaming
Provider events as ZStream
Multi-provider
Combine multiple providers with configurable strategies
Comparison with Java SDK
Aspect
Java SDK
ZIO OpenFeature
Provider management
Global singleton
ZIO Layer
Error handling
Exceptions + defaults
Typed effects
Context scoping
Thread-local
Fiber-local
Transactions
Not available
Built-in
Hooks
Callbacks
Effects (UIO)
Events
Callbacks
ZStream + handlers
Tracking
Blocking calls
Effect-based
Provider SDK Version Compatibility
ZIO OpenFeature ships with OpenFeature Java SDK 1.20.1. You may use providers compiled against older SDK versions, with the following considerations:
Providers implementing FeatureProvider directly — fully compatible. The FeatureProvider interface is identical from v1.14.1 through v1.20.1. No abstract methods were added; every new method (e.g., track()) was introduced with a default no-op implementation. A provider JAR compiled against any 1.14.x+ SDK will work at runtime without recompilation.
Providers extending EventProvider — requires SDK 1.16.0+. In SDK v1.16.0, the emit() and emitProvider*() methods changed their return type from void to Awaitable. Since return types are part of JVM method descriptors, a provider compiled against a pre-1.16.0 SDK that calls this.emit(...) will fail at runtime with NoSuchMethodError. Most ecosystem providers (flagd, LaunchDarkly, Optimizely, etc.) extend EventProvider, so they need to be compiled against SDK 1.16.0+.
Recommendation: Use provider versions that target the same SDK generation as this library (1.16.0+). When in doubt, check the provider’s declared dev.openfeature:sdk dependency version.
Not Implemented
The following OpenFeature features are not exposed in the ZIO wrapper:
