feat(flags): Add $feature_flag_error property to track flag evaluation failures
#2782
+307
−26
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds feature flag error tracking to the Node.js SDK by implementing a $feature_flag_error property in $feature_flag_called events, matching the Python SDK's existing implementation. The property is only set when errors occur during flag evaluation, such as network failures, missing flags, server-side computation errors, or quota limits.
Key changes:
- Added
FeatureFlagErrorconstant object with typed error values for standardized error reporting - Modified
getFeatureFlag()to detect errors and set the$feature_flag_errorproperty when appropriate - Updated core library to preserve the
quotaLimitedfield in API responses for error detection
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| packages/node/src/types.ts | Adds FeatureFlagError constants and FeatureFlagErrorType type for standardized error tracking values |
| packages/node/src/client.ts | Updates getFeatureFlag() to switch from getFeatureFlagDetailStateless to getFeatureFlagDetailsStateless to access error information, detects errors, and conditionally adds $feature_flag_error property to captured events |
| packages/core/src/posthog-core-stateless.ts | Preserves quotaLimited field in the response when quota limits are hit, enabling error detection in consuming SDKs |
| packages/node/src/tests/feature-flags.flags.spec.ts | Updates existing error handling test and adds comprehensive test suite covering all error scenarios (flag_missing, errors_while_computing_flags, quota_limited, unknown_error, multiple errors, and success cases) |
| .changeset/cruel-knives-tan.md | Adds changeset documenting this as a minor version change |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Contributor
|
Size Change: +2.73 kB (+0.05%) Total Size: 5.3 MB
ℹ️ View Unchanged
|
Contributor
There was a problem hiding this comment.
Additional Comments (1)
-
packages/core/src/posthog-core-stateless.ts, line 732-738 (link)logic: missing
errorsWhileComputingFlagsfield in quota-limited return
4 files reviewed, 1 comment
dustinbyrne
reviewed
Dec 17, 2025
Add error tracking for feature flag evaluations, mirroring the Python SDK implementation (PostHog/posthog-python#390). Changes: - Add `FeatureFlagError` constants and type to `types.ts` - Update `getFeatureFlag` to track errors and include `$feature_flag_error` property in `$feature_flag_called` events - Add tests for error tracking scenarios Error types tracked: - `errors_while_computing_flags`: Server returned `errorsWhileComputingFlags` - `flag_missing`: Requested flag not in API response - `unknown_error`: Request failed (network error, timeout, etc.) Note: `quota_limited` detection is not supported because the core library filters out the quotaLimited field before returning. A TODO was added to consider updating the core library to preserve this information.
Preserve quotaLimited field in core library response so Node SDK can detect when feature flags are unavailable due to quota limits.
Makes the test name more specific by including the exact error type (unknown_error) being tested, aligning with the pattern used in other tests in the same file.
e7dbb9e to
a461154
Compare
Remove TIMEOUT, CONNECTION_ERROR, and apiError() which were added for future use but are not currently implemented. These can be added back when the core library is updated to preserve HTTP status information for proper error differentiation.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a port of PostHog/posthog-python#390
Problem
When feature flag evaluations fail (network errors, missing flags, server-side computation errors, quota limits), there's no standardized way to track and analyze these failures. This makes it difficult to debug issues and understand feature flag reliability in production.
The Python SDK already implements a
$feature_flag_errorproperty for this purpose. Node.js SDK users need the same observability capability.Changes
Adds a
$feature_flag_errorproperty to feature flag events in the Node.js SDK, matching the Python SDK's implementation. This property is only set when errors occur during flag evaluation.Error types tracked:
errors_while_computing_flags- Server returned errors while computing flagsflag_missing- Requested flag not in API responsequota_limited- Feature flags billing quota exceededunknown_error- Request failed completely (network error, timeout, etc.)Multiple errors can occur simultaneously and are comma-joined (e.g.,
"quota_limited,flag_missing").Implementation details:
FeatureFlagErrorconstant object with typed error valuesgetFeatureFlag()to detect errors and set$feature_flag_errorpropertyquotaLimitedfield in responses (was previously stripped)Note
The
FeatureFlagErrorconstants includeTIMEOUT,CONNECTION_ERROR, andapiError(status)for future use, but these are not yet implemented. Specifically, HTTP 429 rate-limiting errors currently fall intoUNKNOWN_ERRORbecause the core library catches HTTP errors and returnsundefined, losing the status code.To properly distinguish 429 errors from other failures would require modifying the core library's error handling to preserve HTTP status information, which affects the contract between core and all SDK consumers (Node, browser, React, etc.). This is deferred to a future PR to keep this change focused on parity with the Python SDK.
Release info Sub-libraries affected
Libraries affected
Checklist
If releasing new changes
pnpm changesetto generate a changeset file