Make one flag depend on another
Hold a flag's rollout back until other flags are on for the same person, so a feature never appears without the one it needs.
- Time
- About 6 min
- Who can do it
- Developer, Release manager or Admin. In a production environment, Release manager or Admin.
- Where
- A flag's Targeting & rollout tab, step 4 Prerequisites
- You finish with
- A flag whose rollout waits for the flags it depends on
What and why#
What it is#
A prerequisite is another flag in the same project that must be on for the same person before this flag's percentage rollout applies. If a new checkout needs the new payments service, make the checkout flag depend on the payments flag: the checkout never reaches someone who does not have payments.
When to use it#
- One feature is built on top of another, and showing the top without the base would break the page.
- You want a single switch to pause several features. Turn the base flag off and everything that waits on it stops widening.
- Do not use it to group flags or to copy a state between them. A prerequisite only gates the rollout.
How it works#
Prerequisites are set per environment. FlagSwift decides a flag in this order: kill switch, the flag's own on or off switch, people you named, segments, rules, then prerequisites, then the percentage rollout. Because prerequisites come after the named, segment and rule steps, people matched there are never held back. Everyone else gets the flag's default value while a prerequisite is off.
Before you start#
- Both flags must be active flags in the same project, and configured in the environment you are editing.
- Permission:
flags.updateandrollouts.updatein that environment. Developers and Product managers cannot change production directly, and an environment that requires approval refuses the change withAPPROVAL_REQUIRED. - The flag you edit must be switched on in that environment for prerequisites to matter, because the on or off switch is checked before anything else.
Walk through it#
Open the flag's targeting
Open Flags, choose the flag that should wait, open the Targeting & rollout tab and pick the environment. The steps are numbered and checked top to bottom.
Choose the prerequisites
Step 4 is called Prerequisites. It shows the other flags in the project and environment as buttons. Select each flag that must be on, then choose Save changes in the bar at the bottom. A flag can list up to 10 prerequisites in one environment.
Step 4, Prerequisites, in Production. Selected flags are highlighted; the line below lists flags that depend on this one. You should see. Selected flags are highlighted. If there are none to pick, the step says “No other flags in this project and environment.”Read the rules back
The same step lists any flags that depend on this one, with a link to each and the environment. Turning this flag off blocks their rollouts, so check the list before you do.
Test with the inspector
Open Check who gets this flag at the bottom of the tab, enter a User (or Account or Device) and choose Check. When a prerequisite is not on for that person, the result is Not served with the reason
DEPENDENCY_BLOCKEDand the note “a prerequisite flag is not ON for this person”.The inspector when a prerequisite is off for the person you check. It tests the saved settings, so save your changes first. The inspector accepts up to 255 characters in each field and needs at least one of User, Account or Device. Check stays disabled until you type one.
You should see. Switch the prerequisite on and check again: the same person now gets the normal rollout result, such asROLLOUT_INorFULL_ROLLOUT.
What a prerequisite holds back
Checks on save#
FlagSwift checks every change when you save it and refuses the ones that could not work:
| Rule | Code | Description |
|---|---|---|
| A flag cannot depend on itself | 400 | Choose a different flag. |
| The prerequisite must be an active flag in that project and environment | UNKNOWN_DEPENDENCY | Archived flags, flags in another project and flags not configured in the environment do not count. |
| No loops | DEPENDENCY_CYCLE | Two flags cannot depend on each other, directly or through others. The error shows the path, such as a → b → a. |
| A chain is at most 5 flags long | DEPENDENCY_TOO_DEEP | Counted including the flag itself. Adding a prerequisite also counts chains that pass through this flag. |
| At most 10 prerequisites per flag per environment | 400 | Combine related prerequisites into one flag if you need more. |
| Archive or move a flag that others need | FLAG_IS_PREREQUISITE | Remove the dependency from the flags named in the message first. |
| Move a flag that has prerequisites | FLAG_HAS_PREREQUISITES | Prerequisites are looked up inside one project, so remove them before moving. |
A broken prerequisite fails closed
UNKNOWN_DEPENDENCY.Do it with the API#
Set prerequisites for one environment
This is a Dashboard API call, so it authenticates with your signed-in session cookie, not an API key. Send dependencies with the flag keys; sending the full list replaces the old one, and an empty list clears it. To see what depends on a flag, call GET /api/flags/FLAG_ID/dependents, which returns { "items": [{ "flagId", "flagKey", "flagName", "environment" }] } (permission flags.read).
# Dashboard API: session cookie, permission rollouts.update
curl -X PATCH "https://flags.example.com/api/flags/FLAG_ID/environments/production" \
-b jar.txt -H "Content-Type: application/json" \
-d '{"dependencies":["new-checkout","payments-v2"]}'{
"status": "success",
"message": "Environment updated successfully",
"data": {
"id": "b7d2e4f1-91c3-4a58-8e60-2c1f7a9d3b05",
"name": "express-pay",
"environments": {
"production": {
"enabled": true,
"rolloutPercentage": 25,
"dependencies": ["new-checkout", "payments-v2"],
"version": 6
}
}
}
}What to check#
- With the prerequisite off, a person outside any targeting gets
DEPENDENCY_BLOCKEDin the inspector. - With it on, the same person gets the normal rollout result.
- Try to make two flags depend on each other and confirm the loop is refused.
- The change shows in the flag's History & rollback tab as a rollout entry, and in the audit log.
Good to know#
Prerequisites are per environment
Does a prerequisite mean the prerequisite flag must be 100% on?
Is someone I named in Always on for blocked when a prerequisite is off?
Why can I not archive a flag?
Can I use a flag from another project?
If something goes wrong#
Not an active flag in this project and environment: x (UNKNOWN_DEPENDENCY)
Why: The key is misspelled, the flag is archived, or it has no configuration in this environment.
Fix: Pick the flag from the buttons in step 4 instead of typing a key, and restore the flag if it was archived.
Flags cannot depend on each other in a loop (DEPENDENCY_CYCLE)
Why: The new prerequisite already depends, directly or through others, on this flag.
Fix: Follow the path in the message and remove one link in that chain.
Dependency chains can be at most 5 flags long (DEPENDENCY_TOO_DEEP)
Why: The new link would make a chain, or a chain through another flag, longer than 5.
Fix: Flatten the chain: make the top flag depend directly on the base flag.
Production requires approval. Propose a release instead of changing it directly (APPROVAL_REQUIRED)
Why: The environment requires approval, so direct changes are refused.
Fix: Use a release to apply the change, or ask an Admin to adjust the environment.
Everyone sees the default and the inspector says DEPENDENCY_BLOCKED
Why: A prerequisite is off, at 0%, or does not reach this person in the environment.
Fix: Open the prerequisite flag in the same environment and check its switch, rollout and targeting.