Flag Prerequisites

When you run new experiments or roll out new feature flags, some features only apply to users if another feature is also enabled. Evaluate those dependencies first, then use the results in the evaluation of your flag or experiment.

Experiment lets you create dependencies for your flags and experiments on prerequisite flags or experiments.

Configure flag prerequisites

Configure flag prerequisites in the Dependencies card for the feature flag. Go to Experiment > Feature Flags > your feature flag and scroll to the Dependencies card.

This card summarizes all dependencies for that feature flag, including its prerequisite flags, experiments, mutual exclusions, and holdout groups. The card also lists the flags and experiments that depend on it.

To configure new prerequisites, select the edit icon.
Select Add Dependency to add a new prerequisite flag or experiment.
Select Select a flag or experiment, then select the item you want.

A flag or experiment qualifies as a prerequisite if:

- It's in the same project. - It has a compatible evaluation mode. Local evaluation mode flags and experiments can only have local evaluation mode prerequisites. Remote evaluation mode flags and experiments can have both remote and local prerequisites.

You can't add a prerequisite that creates a circular dependency loop.

Select the variants the flag depends on. A special variant, Off, represents users that the prerequisite flag or experiment excludes.
Select Save.

Workflow considerations

Before you activate a flag or start an experiment, confirm that prerequisite flags are active and that your variant assignment works as expected. You can't start the experiment until its prerequisite flags and experiments are active.

For flags and experiments with dependents, Amplitude blocks the following actions:

Deleting a variant or changing a variant key if another flag or experiment depends on it.
Archiving that flag or experiment.

How evaluation works with prerequisite flags

This example shows how evaluation works when prerequisite flags exist.

For example, you want your new feature flag (Flag-B) to roll out only to users who first saw a different feature (Flag-A). In Flag-B, you add a dependency on the On variant of Flag-A and activate both flags.

When Amplitude evaluates users for Flag-B:

Amplitude checks if the user is in Flag-B's cohort.
- If the user belongs to the cohort, Amplitude serves the configured variant.
Amplitude then evaluates the user for dependencies, in this case Flag-A.
- If the user doesn't receive the On variant for Flag-A, Amplitude excludes them from Flag-B.
Amplitude then evaluates the user for Flag-B.

Targeting for Flag-B determines which variant (if any) the user receives. The flag dependency on Flag-A has no effect at this point.

Prerequisites compared to user property targeting

You can achieve similar outcomes using either flag prerequisites or targeting rules based on [Experiment] user properties. The two approaches differ in important ways.

Use `[Experiment]` user properties in targeting

When Amplitude assigns a user to a flag or experiment variant, Amplitude sets a user property in the format [Experiment] <flag_key> with the variant key as the value. You can reference this user property in another flag's targeting rules to target users based on their previous assignments.

Example: Target users where [Experiment] Flag-A equals on.

Limitations:

Timing issues: Amplitude sets the [Experiment] user property when it ingests the assignment or exposure event. If you evaluate a dependent flag before the property syncs, the user may not match the targeting rule.
No formal dependency tracking: The UI doesn't show the relationship between flags. You must manually track which flags depend on others.
Potential inconsistency: Race conditions between property sync and flag evaluation can give users inconsistent experiences.

Use flag prerequisites

Flag prerequisites formally define dependencies between flags. When you add Flag-A as a prerequisite for Flag-B, Amplitude evaluates Flag-A first and uses the result to determine Flag-B eligibility.

Advantages:

Evaluated together: Amplitude evaluates prerequisites in sequence during a single evaluation call, which eliminates timing issues.
Visible dependencies: The Dependencies card shows all relationships, making complex flag hierarchies easier to manage.
Consistent bucketing: Users get consistent experiences because prerequisite evaluation happens atomically.
Protected changes: Amplitude prevents you from archiving prerequisite flags or changing variant keys that other flags depend on.

When to use each approach

Use case	Recommended approach
Assign users to Flag-A before they see Flag-B	Flag prerequisites
Build release groups with sub-features	Flag prerequisites
Chain mutually exclusive experiments	Flag prerequisites
Target users exposed to a flag days or weeks ago	User property targeting
Analyze experiment results by previous flag exposure	User property targeting
Run ad-hoc segmentation for debugging	User property targeting

Common use cases

Flag prerequisites support many use cases. Common examples include:

Release groups

Use flag prerequisites to build a primary feature with multiple sub-features. Sub-features require the primary feature to be On unless the cohort in a sub-feature individually includes the user. Amplitude applies the targeting and bucketing from the primary feature to every sub-feature that lists the primary feature as a prerequisite. Otherwise, the users receiving the primary feature and the sub-features wouldn't match.

Common use cases for release groups:

Active development of large feature releases across many developers and teams.
Provisioning users to primary SKUs with add-ons.
Simplifying feature flag logic in code.

Diagram of example release group.

This example contains a primary-feature flag and sub-feature flags that list the primary feature as a prerequisite.

The primary-feature flag targets all users where the user property premium is true with 100% allocation. Sub-features only evaluate if the user has the required user property and meets the sub-feature's criteria. The exception is when the sub-feature individually includes the user, which typically occurs during a testing phase.

The sub-feature-1 flag adds targeting criteria for users where the user property beta is true. To receive sub-feature-1, a user must have both premium and beta user properties equal to true.
The sub-feature-2 flag allocates 100% of users. Amplitude assigns every user with premium equal to true to this feature.
The sub-feature-3 flag allocates 0% of users. Amplitude allocates no users to sub-feature-3, even if premium is true.

Chained mutual exclusion groups

Use flag prerequisites to build complex hierarchies of mutually exclusive experiments that start at different times. Dependent experiments list a prerequisite on an existing active experiment evaluating to off. This rule targets all users that the existing experiment didn't allocate. Continue this chain to add more mutually exclusive experiments when the previous experiment doesn't allocate all users.

Diagram of example mutual exclusion group

In this example, experiment-1 runs now, and experiment-2, which is mutually exclusive to experiment-1, runs at a later time.

The experiment-1 experiment allocates 20% of users 50/50 control/treatment.
The experiment-2 experiment lists experiment-1 as a prerequisite and allocates 100% of users 50/50 control/treatment.

Experiment assigns 20% of users to experiment-1 and the remaining 80% to experiment-2. Experiment doesn't assign any user to variants for both experiment-1 and experiment-2.

Was this helpful?