Feature flag bug: how to debug unexpected feature flag behaviour

The first ten minutes \u2014 establish facts before touching code.

• 1Check the flag's targeting rules in the flag management dashboard. Are they correct? Are percentage rollouts adding up right?
• 2Check if the flag value is being cached. Some flag SDKs cache values and only refresh periodically. A recent change might not have propagated.
• 3Check the flag evaluation context. What user attributes are being sent? Is the user ID correct? Are custom attributes present?
• 4Check the default value. If the flag service is down or the SDK cannot reach it, the default value is used. Is the default what you want?
• 5Check if the flag is evaluated server-side, client-side, or both. The value might differ between SSR and browser.

The specific files, logs, configs, and dashboards that usually own this bug.

• searchFeature flag service dashboard — targeting rules, percentage, per-environment overrides
• searchFlag evaluation code in the application — what context is passed? What is the default value?
• searchFlag SDK configuration — cache TTL, streaming/ polling mode, offline fallback
• searchApplication logs — log the flag key, evaluation context, and result for each evaluation
• searchNetwork requests — is the flag SDK successfully connecting to the flag service?
• searchEnvironment configuration — is the flag service using the correct environment SDK key?

Practical causes, not theory. These are the things you will actually find.

• warningTargeting rule logic is wrong — e.g. 'user email ends with @company.com' but condition uses 'starts with'
• warningFlag value is cached and a recent change has not been picked up
• warningFlag SDK is using the wrong environment key — staging key in production
• warningDefault value returns `true` when the flag service is unreachable — unintentionally enabling the feature
• warningUser context is incomplete — user ID or attributes are missing when the flag is evaluated
• warningFlag is evaluated before the user is authenticated — the context has no user data
• warningPercentage rollout is calculated differently than expected (e.g. hash-based, not random)

Concrete fix directions. Pick the one that matches your root cause.

• buildLog every flag evaluation with the flag key, user context snippet, and result — create an audit trail
• buildSet the flag's default value to the safe state (usually `false` for new features) in case the service is unreachable
• buildExpose a debug endpoint or header that shows all flag evaluations for the current request (dev/staging only)
• buildTest flag changes in a staging environment with the same SDK configuration before rolling to production
• buildUse gradual rollout: 1% → 10% → 50% → 100%, monitoring error rates at each step

A fix you cannot prove is a guess. Close the loop.

• verifiedChange a flag targeting rule in the dashboard and verify the application picks up the change within the expected propagation delay.
• verifiedTest with a specific user ID that should and should not have the flag. Confirm both cases.
• verifiedSimulate the flag service being down — the application should use the safe default, not crash or enable features.
• verifiedVerify flag behaviour is consistent across page reloads and sessions for the same user.
• verifiedCheck flag evaluation logs to confirm the context and result match expectations.

Things that make this bug worse or harder to find.

• warningSetting the default value to `true` for a new feature — if the flag service is down, everyone sees untested code
• warningNot testing flag behaviour with the flag service unreachable
• warningUsing the same flag key for different features in different environments
• warningNot logging flag evaluations — when something goes wrong, you have no record of what the flag returned
• warningRolling a flag to 100% immediately instead of ramping up gradually