Find out why someone got a result
When a person gets a result you did not expect, run the real evaluation for them and read the reason it returns.
- Time
- About 6 min
- Who can do it
- Anyone who can read flags (flags.read). Every built-in role can.
- Where
- Flags > your flag > Targeting & rollout > Check who gets this flag
- You finish with
- The result, its reason code and the numbers behind it
What and why#
What it is#
The inspector runs the same evaluation engine your SDKs use, for one person and one environment, against the settings you have saved. It changes nothing, records no event and does not count as an evaluation in your metrics. The answer is a result (Served or Not served), the variant if the flag has variants, and a reason that names the step that decided.
When to use it#
- A customer says they cannot see a feature, or that a colleague sees it and they do not.
- You just added a list, segment or rule and want to prove it works before telling anyone.
- You are partway through a rollout and want to know whether a given person is inside the percentage.
How it works#
The engine checks, in order: the kill switch, whether the flag is on, the always-on lists, segments, attribute rules, prerequisites and finally the rollout percentage. The first step that decides gives the reason. For a rollout it also shows the person's bucket, a number from 0 to 9,999 that never changes for that identifier and flag, against the cutoff (the percentage times 100).
Before you start#
- Permission to read flags (
flags.read). Checking a person changes nothing, so every role can do it, auditors and viewers included. - At least one identifier for the person: a user, an account or a device. Each can be up to 255 characters.
- The environment you are asking about. The same flag can differ between environments.
- Your latest edits saved. The inspector reads saved settings, not what is on screen.
Walk through it#
Open the inspector
Open Flags, choose the flag and open the Targeting & rollout tab. Select the environment at the top, then scroll to Check who gets this flag. It is open by default.
Enter who to check
Fill in User (placeholder
User ID or email), Account, Device, or any combination, and choose Check. The button stays off until you enter at least one. Use the same strings your app sends, with the same capitals and no stray spaces.Read the answer
You see a row of facts. Read them left to right:
Three people checked against the same saved settings. Each result row reads the same way: the outcome, the variant if the flag has one, the reason, then the bucket against the cutoff. What the result row shows Item Description Served / Not served Whether the flag is on for this person. Variant badge For a flag with variants, the variant this person gets. Not served shows the off variant. Reason The step that decided. See the table below. segment: … Shown when a segment granted the flag. It names the first selected segment the person is in. bucket N of M (kind) Shown when the person has an identifier of the kind the rollout counts by. They are inside the rollout when N is below M, for example bucket 312 of 500 (user). M is the percentage times 100.You should see. For a listed person: Served andTARGETED_USER. For a person outside a 5 percent rollout: Not served,ROLLOUT_OUTand a bucket above 500.Include attributes when rules matter
The console box takes identifiers only. To test an attribute rule against real values, use Test these rules in the Rules step, which tells you which rule matches and ticks each condition, or call the inspect endpoint below, which also accepts
attributes.Compare with what your app saw
If the inspector and your app disagree, work through the list under What to check. The server evaluation endpoint returns the same reasons when you pass
explain=true, so you can compare like with like.
Reading the reason#
| Reason | Description |
|---|---|
| KILL_SWITCH | An emergency stop is active. Everyone gets the off result. |
| DISABLED | The flag is switched off in this environment. Targeting does not override it. |
| TARGETED_USER | The person, account or device is in the always-on lists and that toggle is on. |
| SEGMENT_MATCH | A segment selected for this environment includes the person. |
| RULE_MATCH | An attribute rule matched. |
| DEPENDENCY_BLOCKED | A prerequisite flag is not on for this person, so the rollout was skipped. People matched by the three steps above are never held back. |
| FULL_ROLLOUT | The rollout is at 100 percent. |
| ROLLOUT_IN | The person is inside the percentage. Served. |
| ROLLOUT_OUT | The person is outside the percentage, or the percentage is 0. |
| NO_IDENTIFIER | The flag rolls out by an identifier you did not enter. Only the first identifier of the chosen kind is counted. |
| ENV_NOT_CONFIGURED / FLAG_NOT_FOUND | The flag has no configuration for the environment, or no flag has that key. These come from the Evaluation API, not the inspector. |
Stickiness explained
Do it with the API#
Inspect a person (Dashboard API)
This is a Dashboard endpoint, so it authenticates with your signed-in session cookie (auth_session), not an API key, and needs flags.read. Send at least one of identifier, account or device. attributes must be a JSON object. inRollout, targeted and ruleMatched show what each step would say on its own, whatever finally decided.
curl -s -X POST "https://flags.example.com/api/flags/$FLAG_ID/environments/production/inspect" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{"identifier":"user-123","account":"acme","attributes":{"plan":"pro"}}'{
"status": "success",
"message": "OK",
"data": {
"enabled": true,
"reason": "ROLLOUT_IN",
"bucketBy": "user",
"matchedSegment": null,
"bucket": 312,
"cutoff": 500,
"rolloutPercentage": 5,
"inRollout": true,
"targeted": false,
"ruleMatched": false,
"variantBucket": null
}
}Ask the Evaluation API for reasons
This is the Evaluation API, which authenticates with a server or admin key in the Authorization header. It evaluates every flag for the person. Without explain=true the reasons are left out. Keep this call on your backend: it returns more than a browser should see. See the Evaluation API.
curl -s -G "https://flags.example.com/api/v1/evaluation/server" \
-H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY" \
--data-urlencode "env=production" \
--data-urlencode "user_identifier=user-123" \
--data-urlencode 'user_attributes={"plan":"pro"}' \
--data-urlencode "explain=true"{
"environment": "production",
"hashVersion": 1,
"version": "f1c2",
"flags": {
"new-dashboard": { "enabled": true, "reason": "ROLLOUT_IN", "version": 7 },
"checkout-layout": { "enabled": false, "variant": "classic", "value": "classic", "reason": "ROLLOUT_OUT", "version": 3 }
}
}What to check#
- The environment in the inspector is the one your key points at.
- The identifier you entered is the same string your app sends, including case.
- You saved your edits before checking.
- If the inspector and your app disagree, look for a different environment, an SDK still serving a cached configuration, or an app that omits the attribute or identifier.
If something goes wrong#
The Check button is greyed out
Why: Nothing has been entered in User, Account or Device.
Fix: Enter at least one identifier.
Enter a user, account or device to check (400 from the API)
Why: The inspect request had none of identifier, account or device.
Fix: Add at least one. Each is at most 255 characters.
The inspector says Served but my app gets the off value
Why: The app is in another environment, uses a different identifier string, does not send the attribute, or still holds an older configuration.
Fix: Compare with explain=true on the server endpoint using the app's exact values, and check how fresh the SDK's configuration is. See Get changes in real time with streaming.
The inspector says Not served, but I expected a rule to match
Why: Attributes are not part of the console box, so a rule cannot match there.
Fix: Use Test these rules, or the inspect endpoint with attributes.
DEPENDENCY_BLOCKED with a note that a prerequisite flag is not ON for this person
Why: The flag depends on another flag that is off for this person, so the rollout step was skipped. Someone matched by a list, segment or rule would not have been held back.
Fix: Check the prerequisite flag for the same person, then fix it there. See Make one flag depend on another.
NO_IDENTIFIER
Why: The flag rolls out by account or device and you entered only a user, or the reverse.
Fix: Enter the kind shown in Roll out by, or change what the rollout counts. See Roll out a feature.
Good to know#
Reproduce before you edit
ROLLOUT_OUT to SEGMENT_MATCH tells you exactly which edit worked.