Troubleshooting

Feature Flags Troubleshooting

Common Feature Flag issues, how they present, and how to diagnose them.

If a flag is behaving unexpectedly, start here before touching code.

Flag Is Always false

Symptoms

• Flag evaluates to false in the API response
• UI behavior never changes
• No runtime errors

Things to Check (in order)

1. Is the flag declared in the registry?

If a flag is not present in the registry:

• it is ignored by design
• remote tools cannot enable it

Fix: add the flag to FeatureRegistry.

2. Is the feature published in GrowthBook?

GrowthBook features must be published.

Unpublished features:

• appear in the UI
• but are not sent to the SDK

Fix: open the feature in GrowthBook and click Publish.

3. Is the feature enabled for the current environment?

GrowthBook evaluates environment enablement before rules and defaults.

If the current environment is not enabled:

• the feature evaluates to null
• the resolver falls back to the registry default

Fix: enable the feature for the active environment.

Unknown feature { id: "<flag-name>" }

Symptoms

• GrowthBook debug logs show Unknown feature
• getFeatures() returns {} or an empty object
• Context and keys appear correct

Root Cause

The feature does not exist in the dataset loaded by the SDK.

This almost always means a project boundary issue.

Things to Check

1. Project mismatch

Ensure that:

• the feature exists in the same GrowthBook project
• the SDK key belongs to that same project

Even if project names look similar, project boundaries are strict.

2. SDK key alignment

The SDK key must be copied from the same project where the feature is defined.

Fix: copy the key again from Settings → SDK Setup in the correct project.

GrowthBook Loads Successfully but No Features Are Available

Symptoms

• init() (or equivalent) succeeds
• Debug mode is enabled
• No network errors
• getFeatures() returns {}

Root Causes

• Feature not published
• Project mismatch
• Wrong SDK key for the intended project

This is a control-plane issue, not a code issue.

Feature Works in GrowthBook UI but Not in the App

Symptoms

• Toggling the flag in GrowthBook UI has no effect
• API response remains unchanged

Checklist

• Feature is published
• Environment is enabled
• Feature key matches exactly (case-sensitive)
• Feature exists in the correct project
• SDK key is correct
• App has been restarted after config changes

Feature Works for Some Users but Not Others

Symptoms

• Flag behaves inconsistently
• Appears to work “randomly”

Likely Causes

• Attribute-based rules (e.g. org, plan, env)
• Missing or mismatched context keys

How to Debug

The GrowthBook provider already logs context in development mode (process.env.NODE_ENV === 'development'):

Evaluating feature flag "enable-my-feature" with context: { userId: '...', siteId: '...', env: '...' }

Context is built from cookies in src/app/api/platform/features/route.ts — verify that:

• Cookie values (siteId, site, id) are present in the request
• Attribute names match GrowthBook rules exactly
• Attribute values match targeting rule expectations

Feature Flags Break After Refactor or Rename

Symptoms

• Flag suddenly stops working
• No GrowthBook errors
• Defaults apply unexpectedly

Root Cause

Context keys or flag names were renamed in code but not in GrowthBook (or vice versa).

Fix:

• Align flag keys
• Align context attribute names
• Avoid silent renames

API Route Fails with Invalid URL

Symptoms

• Error when fetching /api/platform/features from RSCs
• Stack trace mentions Invalid URL

Root Cause

React Server Components require absolute URLs when fetching server routes.

Fix

Ensure the following environment variable is set:

NEXT_PUBLIC_PLATFORM_BASE_URL=https://<domain>

Use it when constructing fetch URLs in RSCs.

This is expected Node.js behavior, not a Feature Flag issue.

GrowthBook Is Down or Misconfigured

Symptoms

• Feature flag API still responds
• All flags fall back to defaults
• No crashes

Explanation

This is expected behavior.

When GrowthBook is unavailable:

• a Noop provider is used
• defaults are enforced
• the application remains stable

If this is not happening, it is a bug.

Debugging Checklist (Quick)

If something is off, verify in this order:

1. Flag exists in registry
2. Feature is published in GrowthBook
3. Project and SDK key match
4. Environment is enabled
5. Context keys match GrowthBook rules
6. App restarted after config changes

If all six are true, the flag will evaluate correctly.

When to Stop Debugging

If:

• registry is correct
• SDK loads features
• context is correct

…and the flag still behaves unexpectedly, stop and re-check the GrowthBook project and feature definition.

Most issues originate there, not in code.

Type Mismatch from Provider

Symptoms

• Flag has unexpected default value despite provider returning a value

Explanation

The resolver in runtime/resolver.ts checks typeof value !== typeof definition.default. If a provider returns a string where a boolean is expected, the resolver silently falls back to the default. Verify the GrowthBook feature value type matches the default type in the registry.