LaunchDarkly "unknown feature flag, returning default value" in CI
By Daniel Zoghalchali·Latchkey
The SDK evaluated a flag key that is not present in the environment it loaded, so it logged "unknown feature flag" and returned the default you passed to the variation call. The client is working; the key or the environment is wrong.
What this error means
LaunchDarkly logs "Unknown feature flag \"my-flag\"; returning default value" and every evaluation of that key returns the fallback. Behaviour differs from local because CI points at a different environment.
LaunchDarkly
[LaunchDarkly] WARN: Unknown feature flag "enable-new-checkout"; returning default value
Diagnose it: did the report reach the service?
Coverage and quality integrations fail in two distinct places: the report was never produced, or it was produced and the upload was rejected. Establish which before touching tokens.
Terminal
# 1. does the report exist and is it non-empty?
ls -la coverage/ && head -5 coverage/lcov.info
# 2. does it reference paths the service can map to the repo?
grep "^SF:" coverage/lcov.info | head -5
# 3. did the upload actually succeed, or just not fail the step?# most uploaders exit 0 on a rejected upload unless told otherwise
Common causes
The flag key is misspelled or archived
The variation call uses a key that does not match any flag in the environment (a typo, or a flag that was archived or deleted).
CI targets an environment where the flag was never created
The flag exists in production but not in the test environment whose SDK key the CI job uses, so the SDK sees no such key.
How to fix it
Confirm the exact flag key and environment
Open the flag in LaunchDarkly and copy its key exactly (keys are case-sensitive).
Confirm the flag exists in the environment tied to the CI SDK key.
Update the variation call, or create the flag in the CI environment.
Assert readiness before evaluating
If evaluations run before the client finishes loading, keys can appear unknown transiently. Wait for initialization first, then evaluate.
Reference flag keys from shared constants to avoid typos.
Create flags in every environment CI runs against, including test.
Wait for client initialization before the first evaluation.
Frequently asked questions
What causes LaunchDarkly "unknown feature flag, returning default value" in CI?
There are 2 common causes: the flag key is misspelled or archived and ci targets an environment where the flag was never created. The variation call uses a key that does not match any flag in the environment (a typo, or a flag that was archived or deleted).
How do I fix LaunchDarkly "unknown feature flag, returning default value" in CI?
There are 2 fixes depending on which cause you have: confirm the exact flag key and environment and assert readiness before evaluating. Work through them in order, since the first is the most common.
What does LaunchDarkly "unknown feature flag, returning default value" in CI actually mean?
LaunchDarkly logs "Unknown feature flag \"my-flag\"; returning default value" and every evaluation of that key returns the fallback.
How do I stop LaunchDarkly "unknown feature flag, returning default value" in CI happening again?
Reference flag keys from shared constants to avoid typos. The prevention section lists 3 changes that keep it from recurring.
