Add $feature_flag_error property to track flag evaluation failures

Track errors in feature flag evaluation by adding a $feature_flag_error
property to the $feature_flag_called event. This helps identify:

- "errors_while_computing_flags": Server returned errorsWhileComputingFlags=true
- "request_error": The /flags API call failed (network error, timeout, etc.)

This provides visibility into why flag evaluations may return null responses,
making it easier to debug issues like missing request IDs.

Author: haacked

posthog/client.py

@@ -1539,6 +1539,7 @@ def _get_feature_flag_result(
         flag_details = None
         request_id = None
         evaluated_at = None
+        feature_flag_error: Optional[str] = None
 
         flag_value = self._locally_evaluate_flag(
             key, distinct_id, groups, person_properties, group_properties
@@ -1563,7 +1564,7 @@ def _get_feature_flag_result(
                 )
         elif not only_evaluate_locally:
             try:
-                flag_details, request_id, evaluated_at = (
+                flag_details, request_id, evaluated_at, errors_while_computing = (
                     self._get_feature_flag_details_from_server(
                         key,
                         distinct_id,
@@ -1573,6 +1574,9 @@ def _get_feature_flag_result(
                         disable_geoip,
                     )
                 )
+                if errors_while_computing:
+                    feature_flag_error = "errors_while_computing_flags"
+
                 flag_result = FeatureFlagResult.from_flag_details(
                     flag_details, override_match_value
                 )
@@ -1588,6 +1592,7 @@ def _get_feature_flag_result(
                 )
             except Exception as e:
                 self.log.exception(f"[FEATURE FLAGS] Unable to get flag remotely: {e}")
+                feature_flag_error = "request_error"
 
                 # Fallback to cached value if remote evaluation fails
                 if self.flag_cache:
@@ -1612,6 +1617,7 @@ def _get_feature_flag_result(
                 request_id,
                 evaluated_at,
                 flag_details,
+                feature_flag_error,
             )
 
         return flag_result
@@ -1814,9 +1820,10 @@ def _get_feature_flag_details_from_server(
         person_properties: dict[str, str],
         group_properties: dict[str, str],
         disable_geoip: Optional[bool],
-    ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int]]:
+    ) -> tuple[Optional[FeatureFlag], Optional[str], Optional[int], bool]:
         """
-        Calls /flags and returns the flag details, request id, and evaluated at timestamp
+        Calls /flags and returns the flag details, request id, evaluated at timestamp,
+        and whether there were errors while computing flags.
         """
         resp_data = self.get_flags_decision(
             distinct_id,
@@ -1828,9 +1835,10 @@ def _get_feature_flag_details_from_server(
         )
         request_id = resp_data.get("requestId")
         evaluated_at = resp_data.get("evaluatedAt")
+        errors_while_computing = resp_data.get("errorsWhileComputingFlags", False)
         flags = resp_data.get("flags")
         flag_details = flags.get(key) if flags else None
-        return flag_details, request_id, evaluated_at
+        return flag_details, request_id, evaluated_at, errors_while_computing
 
     def _capture_feature_flag_called(
         self,
@@ -1844,6 +1852,7 @@ def _capture_feature_flag_called(
         request_id: Optional[str],
         evaluated_at: Optional[int],
         flag_details: Optional[FeatureFlag],
+        feature_flag_error: Optional[str] = None,
     ):
         feature_flag_reported_key = (
             f"{key}_{'::null::' if response is None else str(response)}"
@@ -1878,6 +1887,8 @@ def _capture_feature_flag_called(
                         )
                     if flag_details.metadata.id:
                         properties["$feature_flag_id"] = flag_details.metadata.id
+            if feature_flag_error:
+                properties["$feature_flag_error"] = feature_flag_error
 
             self.capture(
                 "$feature_flag_called",

posthog/test/test_feature_flag_result.py

@@ -442,3 +442,119 @@ def test_get_feature_flag_result_unknown_flag(self, patch_capture, patch_flags):
             groups={},
             disable_geoip=None,
         )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_with_errors_while_computing_flags(
+        self, patch_capture, patch_flags
+    ):
+        """Test that errors_while_computing_flags is included in the $feature_flag_called event.
+
+        When the server returns errorsWhileComputingFlags=true, it indicates that there
+        was an error computing one or more flags. We include this in the event so users
+        can identify and debug flag evaluation issues.
+        """
+        patch_flags.return_value = {
+            "flags": {
+                "my-flag": {
+                    "key": "my-flag",
+                    "enabled": True,
+                    "variant": None,
+                    "reason": {"description": "Matched condition set 1"},
+                    "metadata": {"id": 1, "version": 1, "payload": None},
+                },
+            },
+            "requestId": "test-request-id-789",
+            "errorsWhileComputingFlags": True,
+        }
+
+        flag_result = self.client.get_feature_flag_result("my-flag", "some-distinct-id")
+
+        self.assertEqual(flag_result.enabled, True)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "my-flag",
+                "$feature_flag_response": True,
+                "locally_evaluated": False,
+                "$feature/my-flag": True,
+                "$feature_flag_request_id": "test-request-id-789",
+                "$feature_flag_reason": "Matched condition set 1",
+                "$feature_flag_id": 1,
+                "$feature_flag_version": 1,
+                "$feature_flag_error": "errors_while_computing_flags",
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_flag_not_in_response(
+        self, patch_capture, patch_flags
+    ):
+        """Test that when a flag is not in the API response, we still capture the request_id.
+
+        This is the normal case when a flag doesn't exist or the user doesn't match
+        any conditions - the flag simply won't be in the response.
+        """
+        patch_flags.return_value = {
+            "flags": {
+                "other-flag": {
+                    "key": "other-flag",
+                    "enabled": True,
+                    "variant": None,
+                    "reason": {"description": "Matched condition set 1"},
+                    "metadata": {"id": 1, "version": 1, "payload": None},
+                },
+            },
+            "requestId": "test-request-id-456",
+        }
+
+        flag_result = self.client.get_feature_flag_result(
+            "missing-flag", "some-distinct-id"
+        )
+
+        self.assertIsNone(flag_result)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "missing-flag",
+                "$feature_flag_response": None,
+                "locally_evaluated": False,
+                "$feature/missing-flag": None,
+                "$feature_flag_request_id": "test-request-id-456",
+            },
+            groups={},
+            disable_geoip=None,
+        )
+
+    @mock.patch("posthog.client.flags")
+    @mock.patch.object(Client, "capture")
+    def test_get_feature_flag_result_request_error(self, patch_capture, patch_flags):
+        """Test that when the /flags call throws an exception, we capture it in the event.
+
+        This simulates what likely happened in production: the remote evaluation failed
+        (network error, timeout, etc.), so request_id is never set, and we capture the
+        $feature_flag_called event with a null response, no request_id, and an error.
+        """
+        patch_flags.side_effect = Exception("Network timeout")
+
+        flag_result = self.client.get_feature_flag_result("my-flag", "some-distinct-id")
+
+        self.assertIsNone(flag_result)
+        patch_capture.assert_called_with(
+            "$feature_flag_called",
+            distinct_id="some-distinct-id",
+            properties={
+                "$feature_flag": "my-flag",
+                "$feature_flag_response": None,
+                "locally_evaluated": False,
+                "$feature/my-flag": None,
+                "$feature_flag_error": "request_error",
+            },
+            groups={},
+            disable_geoip=None,
+        )