Flag Not Updating

Problem

A flag value was changed in the SOASAP dashboard, but the running application continues returning the previous value or an unexpected default.

Common observations include:

• the dashboard shows the new value
• the application still returns the old value
• only some replicas return the new value
• a restarted instance returns a different value
• the application returns its code-defined default
• Development reflects the change but Production does not
• one region updates while another remains stale
• the value changes only after restarting the application

A flag update passes through several independent layers. A failure or mismatch at any layer can produce the same visible symptom.

Expected update flow

SOASAP evaluates flags locally. The application does not query the dashboard or SOASAP Cloud on every read. A dashboard change must first reach the SDK’s local snapshot before evaluations can return the new value. See Local Evaluation and Real-Time Synchronization.

The flag value visible in the dashboard and the value currently held by a specific SDK instance are separate states until synchronization completes.

Quick diagnostic checklist

Check in this order:

1. Confirm the flag change was saved.
2. Confirm the correct project.
3. Confirm the correct environment.
4. Confirm the deployed API key belongs to that environment.
5. Confirm the application is evaluating the expected flag key.
6. Confirm the SDK synchronization connection is healthy.
7. Check the time of the last successful synchronization.
8. Compare behavior across instances or replicas.
9. Confirm the application is not overriding or caching the result.
10. Restart only when evidence indicates stale local state or cache recovery is required.

Start with the exact symptom

Identify the specific failure pattern. Each symptom narrows the search area.

Old value returned

The SDK may still hold an older valid snapshot.

Code default returned

The key may be missing, the flag may not exist in the synchronized environment, no valid snapshot may be available, or type validation may have failed.

Only some instances return the old value

The fleet may be partially disconnected or running mixed deployment configuration.

Value changes after restart

The previous process may have held stale state, the restarted process may have restored a different cache, or initialization behavior may differ.

Dashboard shows the wrong value after refresh

The problem may be in dashboard editing or environment selection rather than SDK synchronization.

1. Confirm the change was saved

Before investigating the SDK, verify that the intended dashboard change was successfully saved.

Check:

• the expected flag is open
• the new value is visible after refreshing the page
• the value was changed in the intended environment
• no unsaved editor state remains
• another operator did not immediately overwrite the change
• the flag was not deleted and recreated under another key

Record:

• flag key
• expected value
• project
• environment
• approximate change time
• operator
• affected application version

2. Confirm the project

The same or similar flag key may exist in more than one project.

Verify:

• the dashboard project containing the change
• the project associated with the deployed API key
• the project expected by the application team
• whether the application initializes multiple SOASAP clients

Dashboard Project A → Value Enabled
Application Key     → Project B

Result: the application never receives the change from Project A.

Use explicit project naming in deployment documentation and incident records.

3. Confirm the environment

Environment mismatch is one of the most common reasons a flag appears not to update.

Verify Development, Testing, Preview, Staging, Production, and any custom environments used by the organization. Check both the selected dashboard environment and the API key injected into the running deployment.

4. Confirm the API key

The SDK key determines which project and environment the instance synchronizes.

Check:

• the application has a key configured
• the secret reference is correct
• the key belongs to the expected environment
• the key has not been revoked through regeneration
• the key was not rotated without updating all deployments
• the running process loaded the latest secret value
• different regions are not using different key versions

Possible symptoms of an incorrect key:

• authentication failure
• no initial snapshot
• restored stale cache
• default values
• correct values from the wrong environment
• only newly started instances failing

See API Keys and Invalid API Key.

5. Confirm the flag key

Flag keys must match exactly.

Check for:

• spelling differences
• capitalization differences
• leading or trailing spaces in application configuration
• old key names after a refactor
• renamed constants
• separate keys for similar features
• environment-specific key construction
• accidental prefixes or suffixes
• Unicode or visually similar characters

Dashboard:  checkout-redesign
Application: checkout-redsign

A missing key commonly causes the application to return its explicit default rather than the dashboard value. Centralize flag keys as constants where appropriate, without creating unrelated service coupling.

6. Confirm the expected flag type

A type mismatch may look like an update failure.

Examples:

• application expects Boolean but the flag is String
• application expects Number but receives JSON
• JSON structure changed but application validation rejects it
• numeric value is outside the application’s accepted range
• nullable or missing fields cause fallback behavior

Check:

• dashboard flag type
• SDK evaluation method
• application default type
• JSON schema or application validation
• conversion and parsing logic

Successful synchronization does not guarantee that application-side parsing accepts the new value. See Boolean Flags, String Flags, Number Flags, and JSON Flags.

7. Check synchronization status

A running SDK must receive synchronization updates for dashboard changes to reach its local snapshot.

Check:

• whether SSE is connected
• whether the SDK is reconnecting
• the time of the last successful synchronization
• duration of the current disconnection
• authentication errors
• DNS errors
• TLS failures
• proxy or firewall failures
• service endpoint reachability

Connected does not always mean current

A connection marked healthy does not by itself prove that the expected update has been applied.

Possible cases:

• the instance connected to a different environment
• the change was made before another configuration overwrite
• the application is reading a different key
• application-side caching hides the new value
• only the inspected instance is healthy
• the snapshot update was rejected or could not be processed
• the observed log or metric is stale

Verify:

• the expected project and environment
• last successful synchronization time
• snapshot version or update timestamp, where exposed by the SDK
• evaluation result from the same application instance
• consistency across the deployment fleet

8. Check the last successful synchronization

The most useful freshness signal is the time since the SDK last received valid configuration. Compare flag change time versus last successful synchronization time.

Synchronization happened after the change

Investigate wrong flag key, wrong project or environment, application-side caching, type mismatch, mixed replicas, or application logic.

Synchronization happened before the change

The SDK has not yet received the update. Investigate SSE disconnection, authentication, network, and reconnect behavior.

No successful synchronization recorded

The instance may be operating from persistent cache or explicit defaults.

9. Check whether the instance is using a local snapshot

A disconnected SDK with a valid snapshot continues evaluating the last known value.

This behavior protects application availability but delays configuration freshness. Check when the snapshot was loaded, whether the application restarted recently, whether the snapshot came from synchronization or persistent cache, and whether the instance has remained disconnected since startup. See Offline Operation.

The old value may be correct for the snapshot currently held by that instance even though it is no longer the latest dashboard value.

10. Persistent cache

After restart, an SDK may restore a previously persisted snapshot.

The cache is not authoritative. It stores the last successfully persisted snapshot, which may be stale. Check cache restoration status, cache age, synchronization after restoration, whether the cache belongs to the same project and environment, and whether multiple deployments share an unsupported cache path.

See Persistent Cache, Cache Strategy, and Cache Not Restored.

Do not delete cache first

Deleting a valid cache can make the situation worse during an outage by removing the last available snapshot. Only clear the cache when corruption is confirmed, wrong-environment cache reuse is suspected, SDK-specific troubleshooting requires it, a clean synchronization can be performed safely, and the affected instance can tolerate defaults until synchronization completes.

11. Check application-side caching

The SDK’s snapshot may be current while the application continues using a value cached elsewhere.

Common patterns:

• reading the flag once at application startup
• storing the value in a static field
• dependency injection registering a computed value as a singleton
• memoization without invalidation
• caching the result in Redis or an application cache
• placing the flag value in a user session
• generating frontend configuration only at build time
• caching HTML or API responses at a CDN
• holding the result inside a long-running job
• capturing the value in a closure

Evaluate the flag at the point where updated behavior is expected, or explicitly document the application’s refresh lifecycle.

Startup-only evaluation

Some applications intentionally evaluate configuration only during startup.

In this design, dashboard updates may not affect the current process even when the SDK snapshot is current. Examples include flags controlling dependency registration, middleware construction, routing tables, connection pools, background-worker creation, and static configuration objects.

This is application lifecycle behavior, not necessarily an SDK synchronization failure. Document whether each operational flag is evaluated per request, per operation, on a timer, only at startup, or copied into another configuration system.

Frontend build-time configuration

A frontend application may have embedded a flag value during the build rather than evaluating it at runtime.

In this design, a dashboard update requires a rebuild or a runtime configuration mechanism. Check whether the SDK runs in the browser, whether a server injects runtime configuration, whether the value is compiled into the bundle, CDN cache status, browser asset cache, service worker cache, and deployment version.

Mobile and desktop applications

Distributed clients may not update immediately because of intermittent connectivity, application suspension, background execution limits, old application versions, stale local storage, offline devices, or synchronization that starts only when the app becomes active.

Recommend:

• reproduce on a known connected test device
• confirm application version
• inspect synchronization status where exposed
• compare foreground and background behavior
• account for older supported versions
• verify that the flag key exists in those versions

Fleet-wide convergence is less immediate for intermittently connected clients than for continuously running servers.

12. Check multiple SDK clients

An application may accidentally create more than one SDK client.

Client A → Connected → Updated Snapshot
Client B → Disconnected → Old Snapshot
Application Code → Reads Client B

Check:

• dependency injection registration
• static and instance clients
• one client per request
• separate clients created by different modules
• clients configured with different keys
• background services using a different client
• test clients accidentally used in production code

Use one long-lived client per required project and environment within the process, where supported by the SDK. See SDK Installation.

Check client lifetime

Repeatedly creating and disposing clients can prevent stable synchronization.

Anti-pattern:

Possible symptoms include inconsistent defaults, repeated connections, high reconnect activity, no persistent snapshot continuity, and updates appearing unreliable.

Recommended lifecycle:

13. Check all replicas

In a horizontally scaled deployment, each SDK instance has its own local snapshot and synchronization connection.

A load balancer may route consecutive requests to different replicas, creating apparently random results. Check per-replica synchronization status, last sync time, deployed API key, application version, region, cluster, instance start time, cache source, and configuration checksum or snapshot identifier where exposed.

Attach a non-sensitive instance identifier to diagnostic responses or logs when permitted.

Sticky sessions and routing

Sticky sessions may cause one user or tester to remain routed to a stale instance. Conversely, non-sticky routing may alternate between updated and stale replicas.

Diagnostic approach:

• identify the responding instance
• send repeated requests
• compare results by instance
• test through and around the load balancer where operationally safe
• inspect regional routing
• verify all replicas before declaring recovery

Do not disable production routing protections solely for troubleshooting without an approved procedure.

Check regions and clusters

A partial network or deployment issue may affect only one region or cluster.

Region A → SSE Connected → New Value
Region B → SSE Disconnected → Old Value

Check regional egress, DNS, proxy configuration, TLS trust, secret deployment, application version, rollout status, and synchronization health. One healthy instance does not prove fleet-wide propagation. See Outages and High Availability.

14. Check deployment version

Old and new application versions may use the same flag differently.

Possible cases:

• old version uses another key
• new version expects another type
• default changed between versions
• old version reads once at startup
• new version evaluates per request
• flag branch was removed from one version
• a rollback restored old behavior

Record application version, build identifier, deployment time, runtime environment, and expected flag semantics for that version. Avoid changing the semantic meaning of an existing flag key across incompatible deployments.

15. Check flag semantics and application logic

The value may have updated correctly, but application logic may interpret it unexpectedly.

Flag Value = true

Application Logic:
if flag == false:
    enableNewFeature()

Possible causes:

• inverted Boolean logic
• confusing negative key names
• stale comments
• default inconsistent with expected behavior
• multiple flags controlling the same feature
• later configuration overriding the branch
• user or request eligibility logic outside SOASAP

Log the evaluated value and the selected application branch without logging sensitive context.

Multiple flags controlling one feature

A product feature may depend on more than one flag or configuration condition.

Feature Enabled =
  Global Flag
  AND Service Configuration
  AND User Authorization
  AND Region Availability

A changed flag may not alter the final behavior if another condition remains false. Check parent or prerequisite flags, application configuration, permission checks, region restrictions, account entitlements, maintenance controls, and deployment-level feature toggles.

JSON, Boolean, String, and Number updates

JSON flag updates

Possible problems include deserializing once and caching the object, incompatible schema changes, missing required fields, rejected validation, reading a nested field that did not change, object comparison preventing refresh, mutable object retention, and frontend state that is not re-rendered.

Inspect the raw evaluated value in a safe test environment, validate schema, compare the exact expected field, avoid logging sensitive JSON payloads, provide a safe default structure, and test backward compatibility.

Boolean flag updates

Common mistakes include inverted conditions, double-negative key names, wrong defaults, reading another similarly named flag, startup-only evaluation, hardcoded overrides, environment variables taking precedence, and features disabled by another application condition. Prefer flag names that describe positive behavior where practical.

String and Number flag updates

String issues include case-sensitive comparisons, whitespace, unsupported enum values, cached application options, and normalization differences. Number issues include parsing failures, unit mismatch, range validation, integer versus floating-point assumptions, zero treated as missing, and application clamping. The SDK may return the updated value while application validation substitutes another value.

Default values

Defaults may be returned when no snapshot exists, the flag key is missing, the expected type does not match, initialization has not completed, cache restoration failed, or the application explicitly chooses fallback behavior. See Default Values.

Log fallback events with flag key, expected type, environment identifier, instance identifier, and reason category where available. Never log the API key.

Network and infrastructure checks

Check:

• outbound connectivity to SOASAP Cloud
• DNS resolution
• TLS certificate validation
• system clock correctness
• proxy configuration
• firewall and egress policies
• service mesh rules
• NAT or gateway health
• connection idle timeouts
• load balancer or proxy SSE compatibility
• regional routing

Refer to official connectivity requirements and SDK documentation for endpoint details.

Proxy and SSE behavior

Some proxies and intermediaries may interrupt long-lived SSE connections. Possible symptoms include frequent reconnects, updates delayed until reconnection, one network segment affected, initial synchronization succeeding while live updates stop, and idle connections being closed.

Check proxy idle timeout, response buffering, connection duration limits, corporate outbound proxy behavior, service mesh settings, and gateway logs. See SSE Disconnected.

Authentication after key rotation

A flag-update incident may begin after an API key regeneration. Check whether every deployment received the new key, whether running processes reloaded the secret, whether scheduled jobs still use the old key, whether one region was missed, whether the replacement key targets the correct environment, and whether local cache is masking failed authentication.

See API Keys and Invalid API Key.

Should you restart the application?

Restarting is not normally required for routine flag propagation. Real-time synchronization should update the local snapshot while the process remains running.

Restart may be appropriate when:

• the SDK client was initialized incorrectly
• deployment secrets changed and the runtime does not reload them
• a confirmed stale or corrupted cache must be replaced
• a client lifecycle bug has been corrected
• the process is stuck and SDK-specific guidance recommends restart
• the application evaluates the flag only during startup
• an infrastructure change requires connection recreation

Restart is unlikely to help when:

• the wrong environment was changed
• the wrong flag key is used
• the API key is invalid
• outbound networking remains blocked
• the application caches the value elsewhere
• another replica remains stale
• the flag type is incorrect

Restart decision tree

Flag value is stale
↓
Was the correct project and environment changed?
  No  → Correct the dashboard scope.
  Yes ↓
Is the SDK synchronized after the change time?
  No  → Diagnose SSE, credentials, and networking.
  Yes ↓
Does direct SDK evaluation return the new value?
  Yes → Diagnose application-side caching or logic.
  No  ↓
Are some replicas current and others stale?
  Yes → Diagnose per-instance synchronization and deployment configuration.
  No  ↓
Is the flag key and type correct?
  No  → Correct application evaluation.
  Yes ↓
Is cache corruption or SDK initialization failure confirmed?
  Yes → Follow controlled cache or restart recovery.
  No  → Collect diagnostics and escalate without destructive changes.

Safe restart procedure

When a restart is justified:

1. Record the current synchronization state.
2. Record the last successful synchronization time.
3. Confirm the expected project, environment, key, and flag value.
4. Check whether persistent cache is present.
5. Confirm network connectivity is available.
6. Restart one non-critical instance first.
7. Verify cache restoration or fresh synchronization.
8. Evaluate the flag on that instance.
9. Confirm application behavior.
10. Continue the rollout gradually.
11. Monitor authentication and reconnect errors.
12. Avoid restarting all replicas simultaneously unless required by incident policy.

A canary restart limits the risk of replacing a working stale snapshot with defaults across the entire fleet.

When to clear the cache

Cache clearing is a recovery action, not a general refresh mechanism. Use it only when corruption is reported, the cache belongs to the wrong environment, an SDK upgrade documents incompatible cache state, the cache repeatedly fails validation, or support guidance requires a clean synchronization.

Do not clear every replica’s cache simultaneously during a synchronization outage.

Diagnostic logging

Temporarily collect:

• application version
• instance identifier
• project identifier where safe
• environment name
• flag key
• expected flag type
• evaluated value where non-sensitive
• whether a default was used
• last successful synchronization time
• SSE connection state
• cache restoration status
• process start time
• deployment region or cluster

Never collect:

• full API keys
• authorization headers
• secrets contained inside JSON values
• personal user data unless required and approved

Remove or reduce temporary debug logging after resolution.

Reproduction procedure

1. Use a non-production environment.
2. Select a dedicated test flag.
3. Record its current value.
4. Start one application instance.
5. Confirm initial synchronization.
6. Evaluate and record the value.
7. Change the dashboard value.
8. Record the change time.
9. Observe synchronization status.
10. Evaluate repeatedly using the same instance.
11. Compare direct SDK evaluation with final application behavior.
12. Repeat with a second instance.
13. Disconnect SSE intentionally in staging.
14. Confirm the old snapshot remains active.
15. Restore connectivity and confirm convergence.

This separates SOASAP synchronization behavior from application-specific caching and routing.

Direct SDK evaluation vs application result

Direct SDK result is new, application behavior is old

Likely causes: application cache, startup-only configuration, inverted condition, another flag or authorization check, frontend or CDN cache, or long-running job state.

Direct SDK result is old

Likely causes: stale snapshot, wrong environment, wrong client, disconnected synchronization, wrong flag key, or mixed replicas.

Direct SDK result is default

Likely causes: missing snapshot, missing flag, type mismatch, invalid key, failed initialization, or no cache after restart.

Perform direct SDK checks only through supported diagnostic code or a controlled test endpoint, not by exposing unrestricted production flag data.

Failure-scenario table

Root-cause decision matrix

Resolution by cause

Wrong environment

Apply the intended value in the correct environment and verify the deployment key.

Wrong API key

Update the deployment secret, restart or reload as required by the platform, and verify authentication.

SSE disconnected

Restore network connectivity and allow automatic reconnection.

Wrong flag key

Correct the application key and deploy the change.

Type mismatch

Use the correct evaluation type and compatible default.

Application-side cache

Invalidate or redesign the application cache according to the required refresh behavior.

Stale replica

Restore synchronization or replace the individual instance safely.

Corrupted cache

Follow the controlled cache recovery procedure.

Build-time frontend value

Rebuild the application or move the setting to a supported runtime-evaluation path.

Startup-only evaluation

Restart deliberately or redesign the application to react to runtime changes.

Verifying the fix

The incident is not resolved until all relevant instances have converged, not merely one test request.

• ✓ the correct project is selected
• ✓ the correct environment is selected
• ✓ the expected API key is deployed
• ✓ authentication succeeds
• ✓ SSE is connected
• ✓ last successful synchronization is later than the dashboard change
• ✓ the expected flag key and type are used
• ✓ direct SDK evaluation returns the new value
• ✓ final application behavior reflects the new value
• ✓ every replica and region has converged
• ✓ defaults are no longer used unexpectedly
• ✓ cache health is normal
• ✓ temporary diagnostics have been removed
• ✓ no old deployment remains on incompatible flag semantics

Escalation data

Collect before escalating to SOASAP support or the internal platform team:

• timestamp of the dashboard change
• project name or non-sensitive identifier
• environment
• flag key
• expected type
• expected value
• actual value
• whether the actual value is a code default
• SDK language and version
• application version
• deployment platform
• affected regions or replicas
• last successful synchronization time
• SSE connection state
• relevant sanitized logs
• cache restoration status
• whether direct SDK evaluation differs from application behavior
• troubleshooting steps already performed

Never include full API keys, authorization headers, unrelated customer data, or unredacted secret configuration.

Common misconceptions

"A saved dashboard change is immediately visible to every SDK instance."

Not necessarily. Each instance must receive the update through its synchronization connection.

"If the application is healthy, synchronization must be healthy."

False. The application may continue evaluating a stale local snapshot.

"Restarting is the normal way to refresh flags."

False. Real-time synchronization should update a running SDK without restart.

"Deleting the cache forces the dashboard value to appear."

False. It removes local state but does not fix environment, credential, or network problems.

"If one replica returns the new value, the entire fleet is updated."

False. Every SDK instance synchronizes independently.

"If SSE is connected, the application must use the new value."

False. The application may cache or override the SDK result.

"If the application returns a default, the flag must be disabled."

False. A default can indicate missing snapshot, missing key, type mismatch, or initialization failure.

"Using the same flag name means the same configuration is being read."

False. The same key may exist in different projects or environments.

"A process restart always obtains the newest value."

False. It may restore a stale persistent cache when synchronization is unavailable.

"Changing a flag automatically reconfigures startup-created application services."

False. Application objects configured only during startup may require an explicit lifecycle action.

Prevention

Troubleshooting runbook

Incident owner:
Application:
Environment:
Project:
Flag key:
Expected type:
Expected value:
Actual value:
Is actual value the code default?
Dashboard change time:
Last successful synchronization:
SSE state:
SDK version:
Application version:
Affected instances:
Affected regions:
API key rotation recently performed?
Cache restored at startup?
Direct SDK evaluation result:
Application behavior result:
Application-side cache identified?
Root cause:
Resolution:
Fleet convergence verified:
Completion time:
Retrospective link:

Relationship to other SOASAP concepts

Related documentation

• Real-Time Synchronization
• Local Evaluation
• API Keys
• Persistent Cache
• Offline Operation
• Default Values
• Outages
• Cache Strategy
• SSE Disconnected
• Invalid API Key
• Cache Not Restored
• High Availability
• Security
• SDK Installation
• .NET SDK
• Node.js SDK
• Python SDK
• React SDK
• Boolean Flags
• String Flags
• Number Flags
• JSON Flags