SDK Issues

This page covers common runtime issues with Flagsmith's client-side and server-side SDKs: stale flags, unexpected default values, and trait evaluation mismatches.

Flag updates are delayed or stale

Your application is not seeing flag changes made in the Flagsmith dashboard, or changes take longer to appear than expected.

Client-side SDKs

By default, client-side SDKs fetch flags once during initialisation. If you need live updates without a page refresh, you must enable polling explicitly:

flagsmith.startListening(30000); // poll every 30 seconds

Each poll counts against your plan's API request allowance. Choose an interval that balances freshness against cost.

Server-side SDKs in local evaluation mode

Server-side SDKs in local evaluation mode fetch the full environment document on a refresh interval and evaluate flags locally. The default refresh interval is 60 seconds in most SDKs:

SDK	Parameter	Default
Python	environment_refresh_interval_seconds	60 s
Java	.withEnvironmentRefreshIntervalSeconds(...)	60 s
Ruby	environment_refresh_interval_seconds	60 s
Node.js	environmentRefreshIntervalSeconds	60 s
.NET	EnvironmentRefreshInterval (TimeSpan)	60 s
Go	flagsmith.WithEnvironmentRefreshInterval(...)	60 s
Rust	environment_refresh_interval_mills	60 000 ms
PHP	environmentTtl	null (polling disabled)

If you lower this interval, the SDK will detect dashboard changes faster. If you raise it, you reduce network calls at the cost of staleness.

Server-side SDKs in remote evaluation mode

Remote evaluation makes a network call on every flag check. If responses feel stale, the issue is usually server-side caching. Check whether CACHE_FLAGS_SECONDS or CACHE_ENVIRONMENT_DOCUMENT_SECONDS is set on the API. A high value here delays how quickly dashboard changes reach your SDK.

Real-time updates (SSE)

If you need near-instant propagation without polling, Flagsmith supports Server-Sent Events (SSE). SDKs subscribed to the real-time stream are notified immediately when flag state changes and refresh their cached values on the next evaluation.

• Enterprise feature. Real-time updates require a Flagsmith Enterprise subscription on SaaS, or the real-time service running alongside your self-hosted deployment.
• Supported SDKs. Not every SDK has SSE client support. Check the Real-time Flags page for the current SDK matrix.

If you have enabled real-time updates but changes still aren't propagating, verify that the SDK is configured with the correct real-time URL and that your network allows long-lived HTTP connections to that endpoint.

Related documentation: Server-Side SDKs • Real-time Flags • Caching Strategies

---

SDK initialisation times out

The first call to the SDK (commonly init, getFlags, or constructing the client) hangs and eventually fails, leaving your application without flag data.

Common causes

• Network path to the API is slow or blocked. A corporate proxy, firewall, or VPN may be intercepting outbound HTTPS to edge.api.flagsmith.com (or your self-hosted domain). The SDK can't distinguish "blocked" from "slow" and will sit on the connection until the request timeout fires.
• DNS resolution is slow. Cold containers or restricted DNS (e.g. some Lambda VPC configurations) can add several seconds to the first lookup.
• Default request timeout is shorter than the network round-trip. Most server-side SDKs default to a 10-second HTTP request timeout (Node.js defaults to 30). On a cold start to a self-hosted instance behind a slow proxy, that ceiling is easy to hit.
• Local evaluation fetching a large environment document. The first refresh in local evaluation mode downloads the full environment. For projects with thousands of flags or segments, that response can take longer than a tight default timeout allows.

Steps to resolve

1. Confirm the SDK can reach the API at all: curl -v https://edge.api.flagsmith.com/api/v1/flags/ -H "X-Environment-Key: <your key>" from the same host the SDK is running on. A clean response rules out network and DNS issues.
2. Raise the SDK's request timeout. Each server-side SDK exposes a parameter for this. Examples: request_timeout_seconds (Python, Ruby, Rust), requestTimeoutSeconds (Node.js), RequestTimeout (.NET), WithRequestTimeout(...) (Go), or connectTimeout / readTimeout / writeTimeout on the OkHttp builder (Java). See the Server-Side SDKs reference for the exact parameter and default value for your SDK.
3. Enable debug logging in the SDK to see whether the SDK is making the request, where the time is being spent, and whether it's the initial fetch or a subsequent refresh that is slow.
4. If you're in local evaluation mode and the environment document is large, see the 504 Gateway Timeout guidance. The same fixes (caching, archiving unused flags, splitting projects) apply.
5. If init genuinely cannot succeed in time, configure an offline handler or a default_flag_handler so your application has a sensible fallback rather than blocking on flag data.

Related documentation: Server-Side SDKs • Offline Handlers

---

SDK is returning default values

Your SDK calls are returning the default or fallback value instead of the value configured in the Flagsmith dashboard.

Common causes

• SDK failed to initialise. If the initial getFlags or init call failed (network error, wrong API URL, wrong key), the SDK has no flag data and falls back to defaults.
• Wrong Environment Key. The Client-side Environment Key is different from the Server-side Environment Key. Using the wrong one will either fail authentication or return an empty environment.
• Local evaluation with the Client-side key. Local evaluation requires the Server-side Environment Key. The Client-side key does not have permission to fetch the full environment document.
• Flag not enabled in this environment. Flags can be enabled in one environment but disabled in another. Check the dashboard for the specific environment your SDK is pointed at.
• Offline handler returning stale data. If you have configured an offline handler or local file handler, the SDK may be reading from an outdated snapshot rather than the live API.

Steps to resolve

1. Check your application logs for errors during SDK initialisation. Most SDKs log warnings when the initial fetch fails.
2. Verify the Environment Key in the dashboard and confirm it matches the value your application is using.
3. For local evaluation, confirm you are using the Server-side key.
4. In the dashboard, navigate to the specific environment and check whether the flag is enabled and has the expected value.
5. If you are using an offline handler, verify that the snapshot file is up to date and accessible.

tip

You can define a default_flag_handler (Python) or equivalent in other SDKs to control what happens when a flag is missing or unreachable. This is useful for graceful degradation, but be aware that if it fires unexpectedly, it can mask an initialisation problem.

Related documentation: Offline Handlers • Flags API Authentication

---

Trait evaluation is inconsistent

Segment rules or identity overrides that depend on traits are not matching the way you expect.

Common causes

• Type mismatch. Flagsmith stores trait values with a type (string, integer, float, boolean). If your SDK sends a trait value as a string "42" but the segment rule expects the integer 42, the comparison may not match.
• Case sensitivity on trait keys. Trait keys are case-sensitive. email and Email are two different traits. If your SDK sets Email but the segment rule targets email, the rule will not match.
• Trait not set on the identity. If the trait has never been sent for a given identity, the segment rule will not match. Traits are not automatically created; they only exist once your application sends them via the SDK or API.
• Local evaluation with missing traits. In local evaluation mode, the SDK evaluates segments using only the traits you provide in the get_identity_flags call. If you omit a trait that the segment rule depends on, the rule will not match, even if that trait exists on the server.

Steps to resolve

1. In the dashboard, navigate to the identity and inspect its traits. Confirm the trait key, value, and type.
2. Compare the trait key casing in your code against the segment rule definition.
3. If using local evaluation, ensure you are passing all traits that your segment rules depend on.
4. Test the segment rule in the dashboard by adding the identity manually and checking whether it matches.

Evaluation order

If a flag value surprises you, keep the precedence in mind. Flagsmith evaluates in this order, highest priority first:

1. Identity overrides (set directly on a specific identity).
2. Segment overrides (the first matching segment wins; segments are evaluated top-to-bottom on the feature).
3. Environment default (the value configured on the feature for the current environment).

See Flag evaluation precedence for the full rules.

Related documentation: Identities & Traits • Segments

---

Local evaluation mode isn't behaving as expected

You have enabled local evaluation but flags are not matching dashboard state, or certain features don't work.

Common causes

• Using the Client-side Environment Key. Local evaluation requires the Server-side Environment Key. The Client-side key will either fail to fetch the environment document entirely or return an incomplete one.
• Stale environment document. The SDK refreshes the environment document on a timer (see the refresh interval table above). If you changed a flag very recently, the SDK might not have picked it up yet.
• Inconsistent identifier for percentage-based segments. Local evaluation evaluates everything in-process, including percentage splits. The SDK hashes the identifier you pass to get_identity_flags(...) to decide which bucket the identity falls into. If that identifier differs from the one used elsewhere (or you make a call without one), bucketing will diverge from what you saw via remote evaluation.

Steps to resolve

1. Confirm you are using the Server-side Environment Key.
2. Check the SDK's refresh interval. If you need near-instant updates, lower the interval (but be aware this increases network calls).
3. For percentage-based segments, verify that you are passing a consistent identity identifier. The hash-based bucketing relies on it.
4. Enable debug logging in the SDK to see when the environment document is refreshed and what it contains.

Related documentation: Local Evaluation Mode • Server-Side SDKs