SDK Debugging

Debugging tools

When a user sees an unexpected value, start with the tooling built into the Statsig console and SDKs.

Diagnostics & log stream

Every gate, config, experiment, and layer has both a Setup and Diagnostics tab. The diagnostics view highlights pass/fail rates and bucketing counts so you can spot anomalies over time.

Scroll to the log stream to inspect individual evaluations. Entries arrive within seconds for both production and non-production environments.

Logging levels and expected information

Statsig SDKs emit runtime logs across four verbosity levels:

• Debug – deep tracing meant for onboarding or issue triage.
  • Missing gate/config warnings when a definition is unavailable.
  • Step-by-step messages that follow SDK initialization and evaluations.
• Info – healthy lifecycle events for day-to-day operation.
  • Initialization summaries with source and SDK version details.
  • Notifications when the configuration store is populated.
• Warning – recoverable issues that might affect functionality.
  • Non-critical errors automatically handled by the SDK.
  • gRPC reconnection attempts or similar transient network events.
• Error – critical failures that block expected behavior.
  • Initialization timeouts or outright failures.
  • Fallback notices that indicate gRPC is unavailable or misconfigured.

Evaluation details

Click any exposure in the log stream to drill into the precise rule, user attributes, evaluation reason, SDK metadata, and server timestamps. That detail is often enough to pinpoint why a user received a specific value.

Evaluation reasons

Evaluation reasons answer two questions: where the SDK sourced its definitions and why a particular value was returned. Use them to distinguish between healthy results, overrides, and error states.

Evaluation times

Evaluation timestamps reveal whether an SDK is serving fresh definitions. An up-to-date LCUT (Last Config Updated Time) indicates the SDK has the latest changes. If LCUT lags behind, users may be seeing stale values. This can happen because a browser tab remained open or because a server integration cannot sync.

Mocking Statsig / local mode

Use the following tools to validate code paths without making network requests:

• Local mode: Set localMode to true so the SDK skips network calls and returns default values. This is useful for tests and offline environments.
• Override APIs: Call overrideGate and overrideConfig to force specific values for an individual user or globally.

Use both techniques together to exercise each branch of your application before shipping.

Client SDK debugger

Inspect the exact values a client SDK is using by opening the Client SDK Debugger. It exposes the active user object and every gate/config tied to that client.

• JavaScript / React: Use the Chrome extension.
• iOS: Call Statsig.openDebugView() in v1.26.0 or later.
• Android: Call Statsig.openDebugView() in v4.29.0 or later.

Landing	Gates List	Gate Details	Experiment Details

FAQ

Invalid bootstrap

InvalidBootstrap occurs when a client SDK is bootstrapped with values generated for a different user profile. The bootstrap user must exactly match the runtime user object.

// Server side
const userA = { userID: 'user-a' };
const bootstrapValues = Statsig.getClientInitializeResponse(userA);

// Client side
const bootstrapValues = await fetchStatsigValuesFromMyServers();
const userB = { userID: 'user-b' }; // <-- Different from userA
await Statsig.initialize('client-key', userB, { initializeValues: bootstrapValues });

Even subtle differences count as a mismatch. Adding customIDs or other attributes results in a distinct user object.

const userA = { userID: 'user-a' };
const userAExt = { userID: 'user-a', customIDs: { employeeID: 'employee-a' } };

BootstrapStableIDMismatch

BootstrapStableIDMismatch is similar to InvalidBootstrap but focuses on stableID. Client SDKs generate a stable ID automatically when one is not provided, so mixing empty user objects between server and client code can cause drift.

// Server side
const userA = {};
const bootstrapValues = Statsig.getClientInitializeResponse(userA);

// Client side
const bootstrapValues = await fetchStatsigValuesFromMyServers();
const userB = { stableID: '12345' }; // <-- Server user lacked a stableID
await Statsig.initialize('client-key', userB, { initializeValues: bootstrapValues });

Even if both sides start with {}, the client-generated stable ID may not match the server’s stable ID, which triggers the same mismatch warning.

const userC = {}; // Client SDK auto-generates a stableID
await Statsig.initialize('client-key', userC, { initializeValues: bootstrapValues });

Environments

SDKs inherit their environment from initialization options. If you don't provide an environment, the SDK defaults to production. To verify which environment a user evaluated under, open the diagnostics log stream and inspect the statsigEnvironment property on the exposure entry.

Maximizing event throughput

The SDK batches events and retries failures in the background. When throughput spikes, adjust these options to reduce dropped events:

• eventQueueSize – Number of events flushed per batch. Larger batches increase throughput but use more memory. Keep the value under approximately 3000 to avoid oversized payloads.
• retryQueueSize – Number of batches kept for retrying. The default is 10. Raise this value to retain more data at the cost of higher memory usage.

Tune both settings to match your traffic profile.