fix(flags): honor false payload overrides (#813)

* fix(flags): honor false payload overrides

* fix(flags): keep payload overrides out of fallback cache

* fix(flags): narrow local evaluation value for mypy

Author: marandaneto

.sampo/changesets/gallant-wavetamer-nyyrikki.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: patch
+---
+
+Honor false feature flag payload overrides

posthog/client.py

@@ -2639,8 +2639,10 @@ def _get_feature_flag_result(
         )
         flag_was_locally_evaluated = flag_value is not None
 
-        if flag_was_locally_evaluated:
-            lookup_match_value = override_match_value or flag_value
+        if flag_value is not None:
+            lookup_match_value = (
+                override_match_value if override_match_value is not None else flag_value
+            )
             payload = (
                 self._compute_payload_locally(key, lookup_match_value)
                 if lookup_match_value is not None
@@ -2650,10 +2652,15 @@ def _get_feature_flag_result(
                 key, lookup_match_value, payload
             )
 
-            # Cache successful local evaluation
-            if self.flag_cache and flag_result:
+            # Cache the local evaluation, not a payload lookup override.
+            cached_flag_result = flag_result
+            if override_match_value is not None:
+                cached_flag_result = FeatureFlagResult.from_value_and_payload(
+                    key, flag_value, self._compute_payload_locally(key, flag_value)
+                )
+            if self.flag_cache and cached_flag_result:
                 self.flag_cache.set_cached_flag(
-                    distinct_id, key, flag_result, self.flag_definition_version
+                    distinct_id, key, cached_flag_result, self.flag_definition_version
                 )
         elif only_evaluate_locally:
             if self.feature_flags is None:
@@ -3205,11 +3212,11 @@ def _compute_payload_locally(
         if flag_definition:
             flag_filters = flag_definition.get("filters") or {}
             flag_payloads = flag_filters.get("payloads") or {}
-            # For boolean flags, convert True to "true"
+            # For boolean flags, use lowercase keys ("true" or "false")
             # For multivariate flags, use the variant string as-is
             lookup_value = (
-                "true"
-                if isinstance(match_value, bool) and match_value
+                str(match_value).lower()
+                if isinstance(match_value, bool)
                 else str(match_value)
             )
             payload = flag_payloads.get(lookup_value, None)

posthog/test/test_feature_flags.py

@@ -21,6 +21,7 @@
 )
 from posthog.request import APIError, GetResponse
 from posthog.test.test_utils import FAKE_TEST_API_KEY
+from posthog.utils import FlagCache
 
 
 # This module preserves the legacy single-flag API's compatibility behavior;
@@ -3777,10 +3778,11 @@ def test_boolean_feature_flag_payloads_local(self, patch_flags):
                         "rollout_percentage": 100,
                     }
                 ],
-                "payloads": {"true": 300},
+                "payloads": {"true": 300, "false": 400},
             },
         }
         self.client.feature_flags = [basic_flag]
+        self.client.flag_cache = FlagCache()
 
         self.assertEqual(
             self.client.get_feature_flag_payload(
@@ -3798,6 +3800,34 @@ def test_boolean_feature_flag_payloads_local(self, patch_flags):
             ),
             300,
         )
+
+        # A false override must take precedence over a locally evaluated true value.
+        self.assertEqual(
+            self.client.get_feature_flag_payload(
+                "person-flag",
+                "some-distinct-id",
+                match_value=False,
+                person_properties={"region": "USA"},
+            ),
+            400,
+        )
+
+        cached_result = self.client.flag_cache.get_stale_cached_flag(
+            "some-distinct-id", "person-flag"
+        )
+        assert cached_result is not None
+        self.assertIs(cached_result.get_value(), True)
+        self.assertEqual(cached_result.payload, 300)
+
+        # Locally evaluated false values use the lowercase "false" payload key.
+        self.assertEqual(
+            self.client.get_feature_flag_payload(
+                "person-flag",
+                "some-distinct-id",
+                person_properties={"region": "Canada"},
+            ),
+            400,
+        )
         self.assertEqual(patch_flags.call_count, 0)
 
     @mock.patch.object(Client, "capture")