Skip to content
FlagSwiftDocs

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.update and rollouts.update in that environment. Developers and Product managers cannot change production directly, and an environment that requires approval refuses the change with APPROVAL_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#

  1. 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.

  2. 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.”
  3. 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.

  4. 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_BLOCKED and 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 as ROLLOUT_IN or FULL_ROLLOUT.

What a prerequisite holds back

Prerequisites gate only the percentage rollout. People who are explicitly targeted, in a matching segment or matching a rule are not held back. Everyone else gets the flag's default value while a prerequisite is off.

Checks on save#

FlagSwift checks every change when you save it and refuses the ones that could not work:

What is refused, and the code the API returns
RuleCodeDescription
A flag cannot depend on itself400Choose a different flag.
The prerequisite must be an active flag in that project and environmentUNKNOWN_DEPENDENCYArchived flags, flags in another project and flags not configured in the environment do not count.
No loopsDEPENDENCY_CYCLETwo 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 longDEPENDENCY_TOO_DEEPCounted including the flag itself. Adding a prerequisite also counts chains that pass through this flag.
At most 10 prerequisites per flag per environment400Combine related prerequisites into one flag if you need more.
Archive or move a flag that others needFLAG_IS_PREREQUISITERemove the dependency from the flags named in the message first.
Move a flag that has prerequisitesFLAG_HAS_PREREQUISITESPrerequisites are looked up inside one project, so remove them before moving.

A broken prerequisite fails closed

If a prerequisite later goes missing, is archived or sits in a chain that is too deep, evaluation treats it as not met and the rollout stays blocked. A rollback to a version whose prerequisites are no longer active is refused with 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).

Request
# 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"]}'
Response
{
  "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_BLOCKED in 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

A dependency set in Staging does not exist in Production. Set it in each environment where the rule should hold, and set it in Production before you widen the rollout there.
Does a prerequisite mean the prerequisite flag must be 100% on?
It must be on for the same person. If the prerequisite is a 25% rollout, only the people it reaches pass this check. The prerequisite's own targeting, segments, rules and its own prerequisites are all applied.
Is someone I named in Always on for blocked when a prerequisite is off?
No. Named people, segment members and rule matches are decided before prerequisites, so they still get the flag.
Why can I not archive a flag?
Another flag lists it as a prerequisite in some environment. The error names up to three of them; open each and remove the dependency first.
Can I use a flag from another project?
No. Prerequisites are looked up inside one 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.