fix(server): align FeatureFlagCacheKey shape across put and get paths

The 2.5.0 release added flagKeys and disableGeoip to FeatureFlagCacheKey
and threaded them through getFeatureFlagsFromRemote (put-side), but the
legacy read paths (getFeatureFlagsFromCache, getFeatureFlagError,
getFeatureFlagDetails, getRequestId, getEvaluatedAt) still constructed
the cache key with only the original four fields.

Because the put-side writes under a 6-field key while these read-side
helpers look up under a 4-field key, every cache read from the legacy
flow misses — even after a successful remote evaluation. The visible
symptoms were getFeatureFlagError returning UNKNOWN_ERROR for flags
that actually resolved successfully (it hits the ?: return
FeatureFlagError.UNKNOWN_ERROR fallback when cache.getEntry misses),
$feature_flag_called events on legacy isFeatureEnabled / getFeatureFlag
calls carrying a spurious $feature_flag_error: 'unknown_error' even
though the SDK reached PostHog and got an answer, and
getFeatureFlagDetails / getRequestId / getEvaluatedAt returning null
for flags that were just evaluated.

This change inlines flagKeys = null, disableGeoip = false at each of
the five legacy read sites so their keys match the keys
getFeatureFlagsFromRemote writes when called from the legacy flow
(which always passes those parameters as their defaults). The
evaluateFlags() path is unaffected — it already builds the 6-field
key consistently on both sides.

Adds LegacyCacheKeyRegressionTest with two cases that fail without
this change and pass with it.

Author: Igor Macedo Quintanilha

.changeset/fix-legacy-cache-key-shape.md

@@ -0,0 +1,5 @@
+---
+"posthog-server": patch
+---
+
+Fix the legacy `isFeatureEnabled` / `getFeatureFlag` flow so it stops emitting `$feature_flag_called` events with a spurious `$feature_flag_error: "unknown_error"` after a successful evaluation. `FeatureFlagCacheKey` is now built with the same shape (`flagKeys` and `disableGeoip` included) on every read path, matching what `getFeatureFlagsFromRemote` writes when called from the legacy flow. Affects `getFeatureFlagsFromCache`, `getFeatureFlagError`, `getFeatureFlagDetails`, `getRequestId`, and `getEvaluatedAt`.

posthog-server/src/main/java/com/posthog/server/internal/PostHogFeatureFlags.kt

@@ -220,6 +220,8 @@ internal class PostHogFeatureFlags(
                 groups = groups,
                 personProperties = personProperties,
                 groupProperties = groupProperties,
+                flagKeys = null,
+                disableGeoip = false,
             )
 
         return cache.get(cacheKey)
@@ -648,6 +650,8 @@ internal class PostHogFeatureFlags(
                 groups = groups,
                 personProperties = personProperties,
                 groupProperties = groupProperties,
+                flagKeys = null,
+                disableGeoip = false,
             )
         return cache.getEntry(cacheKey)?.requestId
     }
@@ -670,6 +674,8 @@ internal class PostHogFeatureFlags(
                 groups = groups,
                 personProperties = personProperties,
                 groupProperties = groupProperties,
+                flagKeys = null,
+                disableGeoip = false,
             )
         return cache.getEntry(cacheKey)?.evaluatedAt
     }
@@ -705,6 +711,8 @@ internal class PostHogFeatureFlags(
                 groups = groups,
                 personProperties = personProperties,
                 groupProperties = groupProperties,
+                flagKeys = null,
+                disableGeoip = false,
             )
         return cache.getEntry(cacheKey)?.flags?.get(key)
     }
@@ -824,6 +832,8 @@ internal class PostHogFeatureFlags(
                 groups = groups,
                 personProperties = personProperties,
                 groupProperties = groupProperties,
+                flagKeys = null,
+                disableGeoip = false,
             )
 
         val entry = cache.getEntry(cacheKey) ?: return FeatureFlagError.UNKNOWN_ERROR

posthog-server/src/test/java/com/posthog/server/internal/LegacyCacheKeyRegressionTest.kt

@@ -0,0 +1,79 @@
+package com.posthog.server.internal
+
+import com.posthog.internal.PostHogApi
+import com.posthog.server.createFlagsResponse
+import com.posthog.server.createMockHttp
+import com.posthog.server.createTestConfig
+import com.posthog.server.jsonResponse
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertNull
+
+/**
+ * Regression: the cache key written by `getFeatureFlagsFromRemote` includes the
+ * `flagKeys` and `disableGeoip` fields introduced in 2.5.0, but several read
+ * paths used by the legacy `isFeatureEnabled` / `getFeatureFlag` flow
+ * (`getFeatureFlagsFromCache`, `getFeatureFlagError`, `getFeatureFlagDetails`,
+ * `getRequestId`, `getEvaluatedAt`) constructed the cache key with only the
+ * original four fields. The shape mismatch caused every legacy lookup to miss,
+ * so `getFeatureFlagError` returned `UNKNOWN_ERROR` as its fallback even after
+ * a successful evaluation, and `getFeatureFlagDetails` / `getRequestId` /
+ * `getEvaluatedAt` returned null.
+ */
+internal class LegacyCacheKeyRegressionTest {
+    @Test
+    fun `getFeatureFlagError returns null after a successful legacy getFeatureFlag`() {
+        val flagsResponse = createFlagsResponse("test-flag", enabled = true)
+        val mockServer = createMockHttp(jsonResponse(flagsResponse))
+        val url = mockServer.url("/")
+
+        val config = createTestConfig(host = url.toString())
+        val api = PostHogApi(config)
+        val remoteConfig = PostHogFeatureFlags(config, api, 60000, 100)
+
+        val flagValue =
+            remoteConfig.getFeatureFlag(
+                key = "test-flag",
+                defaultValue = false,
+                distinctId = "test-user",
+            )
+
+        val error =
+            remoteConfig.getFeatureFlagError(
+                key = "test-flag",
+                distinctId = "test-user",
+            )
+
+        assertEquals(true, flagValue, "Legacy getFeatureFlag should resolve the flag")
+        assertNull(error, "Expected no error after a successful legacy evaluation")
+        mockServer.shutdown()
+    }
+
+    @Test
+    fun `getFeatureFlagDetails returns the flag after a successful legacy getFeatureFlag`() {
+        val flagsResponse = createFlagsResponse("test-flag", enabled = true)
+        val mockServer = createMockHttp(jsonResponse(flagsResponse))
+        val url = mockServer.url("/")
+
+        val config = createTestConfig(host = url.toString())
+        val api = PostHogApi(config)
+        val remoteConfig = PostHogFeatureFlags(config, api, 60000, 100)
+
+        remoteConfig.getFeatureFlag(
+            key = "test-flag",
+            defaultValue = false,
+            distinctId = "test-user",
+        )
+
+        val details =
+            remoteConfig.getFeatureFlagDetails(
+                key = "test-flag",
+                distinctId = "test-user",
+            )
+
+        assertNotNull(details, "Expected details for a flag that was just resolved")
+        assertEquals(true, details.enabled)
+        mockServer.shutdown()
+    }
+}