fix!: onError not called if cacheFlags is true and api is not reachable

[talissoncosta]

Summary

• Fix onError callback not being called when cacheFlags: true, no cache exists, and API fails
• Add test case to reproduce and prevent regression of issue onError not called if cacheFlags is true and api is not reachable #348

Problem

When cacheFlags: true is set but no cache exists yet (first-time user), and the API fails, the onError callback was never called. The error was silently swallowed in the catch block at flagsmith-core.ts:517-519.

Before this fix:

• init() resolves successfully (even though API failed)
• onError is NOT called
• User has no way to know initialization failed

After this fix:

• init() rejects with the API error
• onError IS called with the error
• Behavior now matches when cacheFlags: false and API fails

Breaking Change

This is a behavior change for users with cacheFlags: true when:

1. No cache exists yet (first initialization)
2. API request fails

Previously init() would silently succeed; now it properly rejects.

Migration: Users relying on silent failure should add error handling to their init() call or use defaultFlags as a fallback.

Test plan

• Added test: "should call onError when the API cannot be reached with cacheFlags enabled but no cache exists"
• Verified test fails without the fix (TDD)
• Verified all 69 tests pass with the fix

Fixes #348

[jhoermann]

@talissoncosta Does this really have to be a breaking change release? Normally fixes are considered patch releases.

[talissoncosta]

@jhoermann Good question! Normally yes, but @kyle-ssg raised a valid concern: this fix changes behavior in a way that could break existing apps.

Before: When cacheFlags: true and API fails with no cache, init() silently succeeds and onError is never called.
After: init() rejects and onError is called.

The issue is that users might have onError callbacks that throw or have side effects they didn't expect to trigger in this scenario. Since their apps currently "work" (even if incorrectly), this fix could cause unexpected crashes. We decided to err on the side of caution with a major bump. Happy to discuss if you think a patch is more appropriate!

[jhoermann]

@jhoermann Good question! Normally yes, but @kyle-ssg raised a valid concern: this fix changes behavior in a way that could break existing apps.

Before: When cacheFlags: true and API fails with no cache, init() silently succeeds and onError is never called. After: init() rejects and onError is called.

The issue is that users might have onError callbacks that throw or have side effects they didn't expect to trigger in this scenario. Since their apps currently "work" (even if incorrectly), this fix could cause unexpected crashes. We decided to err on the side of caution with a major bump. Happy to discuss if you think a patch is more appropriate!

Ok got it 👍