SDK Health Hub Warnings

Troubleshooting reference for Statsig Health Hub messages in the console, covering SDK health, data freshness, and pipeline status indicators.

Detecting Initializations

Initialization is the step in SDK setup where your SDK downloads the values for your set of Flags (Gates), Experiments, Dynamic Configs, and other configs, and prepares itself to log events. In all SDKs, initialization requires calling a method like .initialize(), with occasional naming variation between SDKs (for example, InitializeAsync in JavaScript).

How to solve: If you're using a less common SDK (.NET, Dart, Unity, PHP) or an older version, this section can appear incomplete by mistake. Otherwise, initialize your SDK. Go to the docs for the SDK you're using.

Initialization Success

Initialization success is the percent of initialization attempts that successfully return values from the Statsig servers.

How to solve: Common issues on client SDKs include adblockers, poor network conditions, or initialize/updateUser calls made without a network connection (common with backgrounded Android apps). If you suspect adblockers, consider setting up a proxy. Poor network conditions are difficult to resolve. Server issues are less common, but may include improper networking restrictions in your cluster, or an unsuccessful custom initialization approach such as an improperly configured data adapter. Check the specific error logs where your Server SDK is running for more information.

Initialization Size

As you add more gates, experiments, and dynamic configs to your project, the size of the initialize() payload grows. On client SDKs, the initialize payload is "evaluated," meaning it contains only the results for a single user. On server SDKs, the payload contains the full set of rules defining the results for all users.

How to solve: Archive stale gates and experiments, and limit the size of any dynamic configs you use. Statsig doesn't recommend storing large amounts of data in Dynamic Configs. Target Apps limit the configs any one client/server key can retrieve, typically to only those needed.

Initialization Time

Initialization is served from CDNs for Server SDKs, and from Statsig's servers for Client SDKs. Initialization time is largely driven by clients' network conditions, but initialization payload size can also contribute.

How to solve: Reduce your initialize size by archiving stale gates and experiments and limiting dynamic config size, as described above.

Detecting Config Checks

Any time you call .checkGate, .getExperiment, .getDynamicConfig, or a similar method in the Statsig SDKs, the SDK sends a "check" event to Statsig's servers. This lets you see usage of your configs and understand user allocation to experiments. If you're using Statsig's gates, experiments, or dynamic configs in your app, you should see data in this field.

How to solve: On client SDKs, adblockers can block exposure data, and exposure events may be lost when users are immediately redirected after a "check" before the SDK sends the event. On server SDKs, a common issue is that the process exits before the SDK sends events, which is typical in serverless situations. Calling .shutdown or .flush on the SDK prevents this. Refer to your SDK reference docs. Another common issue is accidentally disabling exposure logging on your checks or in StatsigOptions, or misconfiguring an event logging API in StatsigOptions.

Config ID Presence

Every config (gate, experiment, or Dynamic Config) in Statsig has an ID type used to randomly bucket users into groups. When that ID is absent from your "checks", Statsig can't accurately bucket those users. All users without the ID are placed in the same bucket, which can unbalance your experiment.

How to solve: Review your code paths to ensure the ID type is correct for where the experiment runs. For logged-out experiments, an anonymous identifier like StableID is most appropriate. You can also add a targeting gate to the experiment to filter out users with a null ID type.

Healthy Evaluation Reasons

When you check a Statsig gate, experiment, or dynamic config, the SDK always provides a value to ensure the customer experience is unaffected if something goes wrong. The SDKs expose "Evaluation Reason" as a key indicator of whether the SDK is in a healthy state when you make checks. The debugging docs discuss reasons in detail.

How to solve:

If your evaluation reason looks like uninitialized, unrecognized, novalues, or loading, review your Initialization Strategy. uninitialized means initialize was not called. loading and novalues often mean that you're checking a config before initialization returns, or that initialization succeeded but returned no values for the user object you're using (for example, you called updateUserSync(), which changes the user without fetching new values for them).
If your evaluation reason looks like error or unsupported, update your SDK version. These reasons indicate that you're attempting to use a rule type that your SDK version doesn't support.
If your evaluation reason looks like: bootstrapstableidmismatch or invalidbootstrap, refer to the debugging guides for these issues.
If your evaluation reason looks like noclient, then you might be trying to check a config outside of the <StatsigProvider> in React.

Detecting Events

In Statsig, you can use the .logEvent() method in any SDK to create metrics that support your experiments. Without events, experiment analysis and Metrics Explorer are unavailable. If you're using Statsig Warehouse Native, this section might appear empty.

How to solve: If you already have a source of events, import them through one of the Integrations or using a data import from your warehouse. Otherwise, start tracking events with .logEvent() in your code. Events may not reach the Statsig platform if you have a misconfigured StatsigOption (such as disableAllLogging), or if you aren't calling .flush or .shutdown before your process exits, which is most common in serverless applications.

Event ID Presence

For an event to be useful in Statsig, it should have at least one ID attached, such as a userID, stableID, or a customID that you define. Some SDKs require at least one ID through typing, but others don't.

How to solve: Ensure your user objects have at least one ID. Statsig can't use events without an ID in experiment analysis.

Latest Versions

Statsig regularly updates SDKs with performance, security, and functionality improvements. Keep your SDK versions up to date. Statsig doesn't always publish official end-of-life notices, so aim to stay on a version no more than 6 months old.

How to solve: Go to your SDK reference to find the latest version.

Client Bootstrapping

Client Bootstrapping uses Server SDKs to provide initialization values to client SDKs. Bootstrapping offers two benefits: the initialization request can run in parallel with other client requests (reducing load times), and the approach improves resilience during a Statsig outage because Server SDKs have continual, uninterrupted access to rulesets.How to solve: Go to the guides on client bootstrapping to assess whether this is the right initialization strategy for your use case.

Target Applications

Target Applications filter the gates, experiments, and dynamic configs that any one SDK key can access. Target Apps reduce payload sizes (a performance benefit) and limit the visibility of server-targeted configs to the frontend (a privacy benefit).

How to solve: Go to the Target Apps page in the console to set up your first target apps.

Was this helpful?