A feature flag platform can seem to be about many things: dashboards, keys, rollouts, experiments. Underneath all of them is one simple idea, the state.

What does “state” mean?

In everyday language, the state of something is its condition at a given moment. A door is in the state “open” or “closed.” A traffic light is in the state “red,” “amber,” or “green.” A bank account is in the state “balance of five thousand rupees.” The state is not the thing itself. It is the current answer to the question, “What is it like right now?”

Programmers use the word the same way. A program has state when it remembers something that can change. Changing state is how programs react to the world. And one of the great ideas of modern software delivery is to take a particular kind of state, the on and off position of a capability, out of the program’s code and keep it in a place where people can change it safely, without releasing new code.

The problem with state buried in code

Suppose a developer wants a new checkout page to be hidden until the business is ready. The simplest approach is to write a line in the code that says “show new checkout: false.” To change it, someone must edit the code, test it, and release a whole new version. If the page misbehaves in production, undoing it needs another release. The state of the capability is hidden inside the program, and changing it means changing the program.

The idea behind a feature state

A feature flag platform moves that decision out of the code. The code asks a question, “Is new checkout on for this user?” and a separate system supplies the answer. That answer, stored and managed outside the program, is the feature state. Because it lives outside the code, a person can change it in seconds, with a click, with proper permissions and a written record.

A short story of a state gone wrong

Rohan works at a food delivery company. His team has a feature for “free delivery above five hundred rupees.” One evening, a colleague edits the state to lower the threshold to fifty rupees, meaning to do it in the test environment. But the screen showed Production. Within ten minutes thousands of tiny orders arrive with free delivery. The team notices the spike in a dashboard, restores the previous state in one click, and the damage is limited to a few thousand rupees. If the threshold had been hidden in code, the same mistake would have needed a release to fix. The lesson is not only that states are powerful, but also that they must be handled with the same care as code: right place, right permissions, and a written history.

A feature state is the stored answer for one feature in one context, made up of an enabled position and, optionally, a value.

A quick map of Flagsmith

Flagsmith is an open-source platform for feature flags and remote configuration. A feature flag is a switch that turns behaviour on or off without a new release. Remote configuration means storing values, such as numbers or text, that an application reads while it runs. Flagsmith arranges everything in a tree.

flowchart TB
    ORG["Organisation"] --> PRJ["Project: Food Delivery App"]
    PRJ --> FEAT["Feature: free_delivery_threshold"]
    PRJ --> ENV1["Environment: Development"]
    PRJ --> ENV2["Environment: Production"]
    FEAT --> FS1["Feature state in Development: enabled, value 50"]
    FEAT --> FS2["Feature state in Production: enabled, value 500"]
    ENV1 --- FS1
    ENV2 --- FS2
    

The simplest definition

If a feature is a labelled hook on a hotel key board, the feature state is whether a key is hanging there and which key it is. The label is the same for everybody. The state is a decision about this hook, in this hotel branch, at this moment.

The two halves of every state

A feature state always has two parts that work together.

• The enabled position. A simple yes or no. Is the feature switched on in this context? This is the classic feature flag.
• The value. Optional information attached to the feature, such as a number, a piece of text, or a small block of structured data. This is remote configuration. Even if the feature is switched off, a value may still be stored.

State versus feature: keep them apart in your mind

Let us open a feature state and look at every part inside it. Each part answers one small question.

flowchart LR
    STATE["One feature state"]
    STATE --> WHICH["Which feature: the name it belongs to"]
    STATE --> WHERE["Where: environment"]
    STATE --> FOR["For whom: everyone, a segment, or one identity"]
    STATE --> EN["Enabled position: yes or no"]
    STATE --> VAL["Value: number, text, or structured data"]
    STATE --> MV["Variation shares if multivariate"]
    STATE --> META["Version, who changed it, and when"]
    

Value types

The value held inside a state can carry different kinds of information. Typically you can store text, whole numbers, true or false values, and, in many versions, structured data written in a common text format used to describe objects. Choose the simplest kind that fits. A single number is easier to read, check, and test than a large block of structured data. If you do store structured data, keep it small and describe its shape in the feature’s description, because mistakes inside a free-form value are not caught until your application tries to use it.

An example state, in words

Take the feature “search_suggestions_limit.” Its state in the Production environment, for everyone, might read: enabled is yes, value is five. Its state for the segment “Mobile users” in the same environment might read: enabled is yes, value is three. Its state for one identity, a tester called “user 4821,” might read: enabled is yes, value is twelve. Three states, all belonging to one feature, all in one environment, each applying to a different audience.

A single feature in a single environment can hold several states at once, stacked in layers. Understanding the order of the layers explains almost every surprise in Flagsmith.

Layer one: the environment default state

Every feature has a default state in every environment. It applies to every user who does not match anything more specific. If you change only this layer, everyone in that environment gets the same new answer. It is the bottom layer, and the one that is always there.

Layer two: segment override states

A segment is a saved group of users, defined by rules about their traits. A trait is a fact stored about a user, such as country, plan, or app version. A segment override is a special state for one feature, in one environment, that applies only to users in the segment. For example, in Production, the “Employees” segment might have the new checkout enabled while the default state is still disabled. Segment definitions are shared across the project, but segment override states are stored separately in each environment.

Layer three: identity override states

An identity is a user, device, or account that your application tells Flagsmith about, normally by sending a unique identifier. An identity override is a special state for one feature, in one environment, that applies to exactly one identity. This is the most specific layer. It is perfect for letting a single customer try a beta, or for letting a support engineer reproduce a bug as a particular user.

flowchart TB
    subgraph LAYERS["Layers of state for one feature in one environment"]
        L3["Layer 3: Identity override state, most specific"]
        L2["Layer 2: Segment override states, in priority order"]
        L1["Layer 1: Environment default state, always present"]
    end
    REQ["Request for identity 4821"] --> L3
    L3 -->|"No override for this identity"| L2
    L2 -->|"No matching segment"| L1
    L3 -->|"Override found"| ANS["Answer"]
    L2 -->|"Segment match found"| ANS
    L1 --> ANS
    

The order of decision

Flagsmith always looks from the most specific layer to the most general. It first checks for an identity override. If none exists, it looks at the segment overrides for segments that the identity belongs to. If several segments match, a priority order that you control decides which wins. If nothing more specific applies, the environment default state is used. The first layer that has an answer provides the answer, and the layers beneath it are ignored for that user.

A state has an enabled position and a value. How your code treats these two together is a choice. Making that choice clearly prevents a whole family of bugs.

Four possible combinations

The common design rule

A very common and sensible rule is: when the state is disabled, use the safe built-in default and ignore the stored value; when it is enabled, use the stored value. This rule makes the off position a reliable emergency exit. Flipping the switch off always returns the application to the behaviour that was there before, whatever number or text happens to be stored.

When the value is the whole point

Sometimes a feature is purely a configuration value and the enabled position is not used at all, such as a setting called “request_timeout_seconds” with the value thirty. In that case, make the team rule explicit: either the value is always read regardless of the switch, or the switch is always kept enabled. Mixed habits cause confusion, because one developer treats “disabled” as “use default” and another treats it as “feature does not exist.”

The same feature holds a separate default state in every environment. This separation is the main safety feature of Flagsmith.

A reminder about environments

An environment is a separate place where your product runs, such as Development, Staging, or Production. In Flagsmith, each environment stores its own states for every feature, and has its own access keys. An application chooses its environment simply by being given that environment’s key.

A picture of the state matrix

If you imagine a table with features down the side and environments across the top, each cell of the table holds a feature state. The table below shows part of such a matrix for a small project.

The size of this matrix grows quickly. Fifty features across four environments means two hundred default states, before counting any segment or identity overrides. This is why tidy habits, such as deleting finished features, matter so much.

The ladder of states

Because states are separate, a feature can climb a ladder, one rung at a time, collecting evidence on each rung. Development changes freely, many times a day. Staging changes when a release candidate is ready. Production changes only when the business is satisfied and the checks are green.

flowchart LR
    D["Development state: on for all, change freely"] -->|"Works as intended"| S["Staging state: set like next Production state"]
    S -->|"Tests pass and owners agree"| P["Production state: employees, then percentage, then all"]
    P -->|"Problem found"| R["Return Production state to previous version"]
    R --> D
    

No automatic copying, by design

When you change a state in Development, nothing happens in Staging or Production. That separation is deliberate, because automatic copying would defeat the protection that environments create. The consequence is that someone must apply the change in the next environment at the right moment. Teams make this step careful with reviewed requests, scheduled changes, and sometimes scripts that apply the same state to the next environment after tests pass.

Healthy differences and drift

Differences between environments are healthy when they are deliberate. A small number in Development makes screens easy to inspect, and a realistic number in Staging tests layout and load. Problems begin when differences are accidental and unexplained, a situation called configuration drift. A state quietly changed in Staging for a demo and never changed back makes the next rehearsal misleading. Compare environments before each release and explain every difference.

Reading the matrix with three questions

When you look at any cell of the state matrix, three simple questions make it easy to understand. First, which environment is this? The same feature may be on in one and off in another, so never read a state without noticing its column. Second, for whom? The cell may hold a default state and also several segment overrides and identity overrides, so the visible switch is only part of the story. Third, since when? A state changed five minutes ago is a very different fact from a state unchanged for two years. The first points to a possible accident, and the second points to a feature that may be ready for cleanup.

Teams that build the habit of asking these three questions find that most confusing reports can be solved in a few minutes. A tester says, “The feature does not work for me.” The engineer asks which environment the tester is using, which segments the tester belongs to, and what changed recently. The answer is usually found within the layers of state, long before anybody opens the code.

Segment overrides are where most of the daily work of controlling who sees what takes place. Let us look closely at how their states behave.

Defined once, decided separately

A segment is described by rules over traits, for example “plan equals premium and country equals India.” These rules are part of the project, so a segment means the same thing in every environment. But the state a segment receives for a given feature is stored per environment. This allows the “Employees” segment to receive the new checkout in Production and also in Staging, while the “Beta” segment receives it only in Staging. The groups are shared, and the decisions are local.

Priority among segments

A user can belong to several segments at once. A premium user in India who is also an employee might match three segments. Flagsmith resolves the conflict with an ordered list: the segment override with the highest priority wins. You can reorder the list in the dashboard. Put the most specific and most important overrides at the top, and the broad ones lower down.

Segment states can carry values and variations

A segment override is not limited to on and off. It can carry its own value, and for multivariate features it can carry its own variation shares. For example, the segment “Premium users” may receive a search limit of twenty, while the default is five. This turns segments into a powerful way to express business rules without changing code.

Common recipes

The most specific layer of state belongs to a single person. Used well, it solves difficult problems. Used carelessly, it creates a mess.

Identities live inside an environment

When your application tells Flagsmith about a user, sending an identifier and perhaps some traits, that identity is recorded in the environment whose key was used. A person who exists in Production does not automatically exist in Staging, unless your Staging application also reported them. This separation is healthy, because test users and real users never get mixed. It also means that traits used by segments must be sent by every environment’s application, or the segments will not match there.

What an identity override does

An identity override is a feature state attached to exactly one identity in exactly one environment. It beats every segment override and the environment default. That is its strength. If a customer’s chief technology officer asks to try a beta capability next week, a single identity override is the cleanest way to grant it. If a support engineer must reproduce a strange bug a customer reports, an identity override on a test account lets her see the system exactly as that customer would.

Traits: facts that drive the layers

Traits are the facts stored about identities, and segments are rules over traits. Because the quality of your segment states depends on the quality of your traits, it pays to design them with care.

• Use stable names. A trait called “plan” should always be called “plan,” in every application and every environment.
• Use consistent values. “premium” and “Premium” are different to a computer. Agree on the exact spellings.
• Keep them small and useful. Send the few facts your rules really need, such as country, plan, and app version.
• Avoid sensitive data. Do not send names, email addresses, or health details as traits unless you truly must, and have a legal reason.
• Send traits from every environment. Otherwise, rehearsals in Staging will not predict Production.

Anonymous users

A visitor who has not logged in has no stable identifier. Applications often create a random identifier, store it in the browser or on the device, and use it as the identity. If the visitor later logs in, their identity may change, and with it their state. Plan for this by deciding whether to use the user, the account, the organisation, or the device as the identity. A business product often uses the company as the identity, so that every employee of one customer sees the same state and support is never confused.

When one yes or no is not enough, a state can hold several variations, each with a share of the users.

What a multivariate state holds

A multivariate feature has a control value, which is the normal behaviour, plus two or more variations, each with its own value. In each environment, the state records a percentage for every variation. The control takes whatever percentage remains. For example, variation B may have ten percent, variation C ten percent, and the control the remaining eighty.

The variations themselves, their names and values, belong to the feature. But the percentages are part of each environment’s state. This lets Development spread users evenly, so developers see every version, while Production exposes only a careful slice to the new ones.

How a person is placed into a variation

Flagsmith must give each person the same variation each time, otherwise a user might see a blue button on one page and a green one on the next. It uses a technique called consistent hashing. The identity’s identifier is combined with the feature’s own identifier and put through a hash function, a mathematical scrambler that always gives the same output for the same input, but whose outputs look random and spread evenly. The output is turned into a number from zero to one hundred, and the variations occupy slices of that range according to their percentages. Because the same inputs give the same number, a user’s experience is stable. And because the feature’s identifier is mixed in, the same unlucky users are not always in the first slice of every feature.

Changing shares mid-experiment

Because the placement is determined by number ranges, changing a percentage shifts the boundaries between slices. Users near a boundary may move from one variation to another. For a gradual rollout, that is acceptable, since you only grow the new variation. For a scientific experiment, it can spoil the results, because a user who saw version B yesterday might see version A today. Treat a change of shares during an experiment as the start of a new experiment.

Feeding experiments with state

A state only decides who sees what. Judging the result is another job. Flagsmith can pass information about the variation a user received to analytics tools through integrations, so that the analysis is done where your business numbers already live. Decide the measurement first, run for whole weekly cycles, and do not stop the moment one side looks better, because chance can easily fool you.

When your application asks about a feature, Flagsmith must pick one answer out of all the stored states. Let us follow that choice step by step.

The question from the application

An application normally asks Flagsmith for flags using an SDK, a small library for its programming language. It supplies the environment key, and, for personalised answers, the identity’s identifier and traits. The SDK then returns, for each feature, the enabled position and the value, which your code uses to choose a behaviour. You also give a default in code, used if no answer can be obtained.

flowchart TB
    START["Request: identity, traits, environment key"] --> FIND["Find the environment from the key"]
    FIND --> LOAD["Load all states for each feature in that environment"]
    LOAD --> ID{"Identity override state exists?"}
    ID -->|"Yes"| PICK1["Use identity state"]
    ID -->|"No"| SEG{"Identity matches a segment with an override?"}
    SEG -->|"Yes"| PICK2["Use highest priority matching segment state"]
    SEG -->|"No"| DEF["Use environment default state"]
    PICK1 --> MULTI{"Is the chosen state multivariate?"}
    PICK2 --> MULTI
    DEF --> MULTI
    MULTI -->|"Yes"| HASH["Place identity in a variation using stable hashing"]
    MULTI -->|"No"| OUT["Return enabled and value"]
    HASH --> OUT
    

Remote evaluation

In remote evaluation, the SDK sends a request over the network, and Flagsmith’s servers run the steps above and reply. This works with the public client-side key and is the normal way for web pages and mobile apps. The cost is a network trip for each fetch, so applications fetch once at the start of a session and keep the answers in memory.

Local evaluation

In local evaluation, a back-end server uses its secret server-side key to download all the states and rules of an environment, called the environment document, and runs the steps itself, from memory. It refreshes the document in the background. Checks become extremely fast, and the server keeps working through a short outage using the last known states. The trade-off is that changes arrive at the next refresh instead of instantly.

The default: your safety net

A default is the behaviour your code uses when it cannot get an answer, for example during a network problem, or if a feature has been deleted by mistake. The best default is almost always the old, proven behaviour. Defaults are written in your code next to the check, not stored in Flagsmith. For a new release feature, the default should be off. A default that turns a brand new capability on when the service is unreachable means a routine network glitch could expose every user to unfinished work.

A state can be changed in several ways. Each way has its own strengths, and teams usually mix more than one.

Choosing a way for each environment

flowchart LR
    A["Person proposes state change in Production"] --> B["Change request created"]
    B --> C{"Reviewer approves?"}
    C -->|"No"| D["Comments and revision"]
    D --> B
    C -->|"Yes"| E{"Apply now or schedule?"}
    E -->|"Now"| F["State changes immediately"]
    E -->|"Later"| G["State changes at chosen time"]
    F --> H["Audit log and webhook"]
    G --> H
    H --> I["Applications receive new state"]
    

What happens at the moment of change

When a state is saved, Flagsmith writes the new state to its store and records the change in the audit log. It may also fire a webhook, a message sent to another system, such as a post in a team chat channel. The delivery layer then makes the new state available to applications. Applications using remote evaluation see it on their next request, and applications using local evaluation see it after their next refresh. The whole journey from click to effect often takes only seconds.

Because a state can be changed in a second, it must also be possible to see what it used to be and to return to it. History is the safety net under every change.

The audit log

The audit log is a diary of everything that changes in Flagsmith: who made the change, which feature and environment it touched, what the old and new states were, and when. When something odd happens in production, the first question is always “what changed?” and the audit log answers in seconds. For compliance, it also proves that changes followed approved procedures.

Feature versioning

In versions of Flagsmith that support feature versioning, the states of a feature in an environment are saved as numbered versions. A new version is created each time changes are published, and earlier versions can be inspected, and in many cases restored. This turns recovery from “try to remember the old value” into “go back to version twelve.” It also allows a new version to be prepared and published together at a chosen time, along with its overrides.

Comments and reasons

A short note explaining why a change was made, such as “raising to twenty-five percent after clean results from ten,” makes the history readable by people who were not there. Make writing such notes a team habit, particularly for Production.

Snapshots and exports

Teams also keep their own record of important states. Some export the environment’s configuration regularly through the Admin API and store it in version control. Others describe states as code with an infrastructure tool, so that the written plan is always the record. Both approaches protect against rare disasters, such as a mistaken bulk deletion, and make drift easy to detect, since the real states can be compared with the saved ones.

Feature states are what make continuous delivery calm. They separate the moment code arrives from the moment users see it.

A quick reminder about the pipeline

Continuous Delivery means every code change travels through an automatic assembly line, called a pipeline, that builds, tests, and prepares it so that it could be released at any moment. The same package moves from stage to stage. Only the settings change, and feature states are among those settings.

Deploy is not release

flowchart LR
    C["Commit"] --> B["Build and tests"]
    B --> DEV["Deploy to Development"]
    DEV --> STG["Deploy to Staging"]
    STG --> PRD["Deploy to Production with state disabled"]
    DEV -.->|"uses Development key"| SD["Development states"]
    STG -.->|"uses Staging key"| SS["Staging states"]
    PRD -.->|"uses Production key"| SP["Production states"]
    SP --> REL["Release: change Production state in steps"]
    

Mirror staging to production

As a release approaches, set the Staging states to match what Production will hold after release, then run the final checks. If Staging holds different states from what Production will hold, the rehearsal answers the wrong question. Add a step before each release that compares the two environments and explains every difference.

Trunk-based development and hidden work

In trunk-based development, everyone merges small changes into one shared main line every day. Half-finished work will land there. A disabled feature state keeps it invisible while it travels to production in the normal pipeline. The state turns the main line into a safe place for unfinished ideas.

A rollout is nothing more than a planned series of state changes. Seeing it as a journey from one state to the next makes it easy to plan, measure, and reverse.

flowchart LR
    S0["State 0: off everywhere, code deployed"] --> S1["State 1: on in Development"]
    S1 --> S2["State 2: on in Staging for testers"]
    S2 --> S3["State 3: Production on for employees"]
    S3 --> S4["State 4: Production on for beta customers"]
    S4 --> S5["State 5: Production on for ten percent"]
    S5 --> S6["State 6: Production on for fifty percent"]
    S6 --> S7["State 7: Production on for everyone"]
    S7 --> S8["State 8: stable, old path kept as exit"]
    S8 --> S9["State 9: code removed, feature deleted"]
    S4 -.->|"Problem"| S3
    S5 -.->|"Problem"| S3
    S6 -.->|"Problem"| S0
    

Each step has an entry rule and an exit rule

Reversal is also a state change

The most valuable property of this design is that reversal is the same kind of action as progress. Moving from state six back to state three is simply another edit of the state, and it takes the same few seconds. No deployment is needed, because the code never left. This is what makes a bold launch calm: the exit is always one click away.

Writing the plan down

Before the first step, write the plan: the states in order, the audience of each, the guardrail numbers to watch, the time to wait at each step, and the person who may press the reverse button. A written plan transforms a nervous rollout into a routine. A good plan also says what the safe state is, so that anyone on call can move there without asking permission.

A state changed in a dashboard does not reach every server at the same instant. Understanding the delay keeps surprises small.

The journey of a changed state

Eventual consistency

For a short while after a change, some servers hold the old state and others hold the new. This is called eventual consistency: all servers will agree in the end, but not at the very same instant. For most capabilities, a few seconds of disagreement is harmless. A user might see a new button on one page load and not on the next. For some journeys it matters more.

Making a decision sticky

For multi-step journeys, such as a checkout of several screens, a change in the middle would be confusing. The common remedy is to read the state once at the start of the journey, store the answer with the user’s session, and reuse that stored answer for the rest of the journey. The next journey reads the state again, and receives the new answer. This is called a sticky decision.

Choosing freshness by importance

When behaviour depends on states that can change at any moment, testing needs a few extra habits.

The explosion of state combinations

If a program has one feature, there are two possible behaviours. With two features there are four, and with ten features there are one thousand and twenty-four. With thirty there are over a billion. Each layer of override adds more possibilities for each user. Nobody can test every combination, and fortunately nobody needs to, since most features do not touch each other. The skill lies in testing the combinations that matter.

A practical approach

Repeatable tests need fixed states

An automatic test must give the same result every time. A test that depends on a state that people change during the day would be unpredictable. The cure is a dedicated test environment in which states are fixed and changed only by the test team, or a wrapper in your code that lets the test supply the answer directly: “for this check, pretend the feature is enabled with value five.” Everything else then behaves normally.

Temporary environments

Larger teams sometimes create a temporary environment for each pull request. The pipeline creates the environment through the Admin API, sets the states the new feature needs, runs the tests, and deletes the environment afterwards. Two developers can then test conflicting states at the same moment. The price is the effort of automation and the need to clean up reliably, since forgotten temporary environments pile up.

Practising the safe state

A kill switch that has never been tested is a hope, not a safety device. Practise setting important states to their safe position in Staging, and occasionally in Production during quiet hours, to confirm that the product degrades gracefully. A page that crashes when recommendations vanish is a problem best found during practice.

Managing behaviour through states gives great power and also real costs. An honest engineer knows both sides.

Key trade-offs to decide on purpose

When not to use a state

Not every setting deserves to be a changeable state. A rarely changed setting that is safe in code, a constant that must be checked at build time, or a secret that should never travel through a flag platform, are all better handled elsewhere. The more things you place behind changeable states, the more places you must watch.

Changing a state can change what millions of people see in seconds. That power must be guarded, and the information flowing through states must be handled with respect.

Who may change which states

Least privilege means each person gets only the permissions needed for their job. Flagsmith lets administrators grant permissions at the organisation, project, and environment levels, to individuals or to groups. At environment level, typical permissions include viewing the environment, updating feature states, managing segment overrides and identities, and creating or approving change requests.

Keys and tokens

Applications read states using environment keys. The client-side key, for web pages and mobile apps, is treated as public, because it can only fetch the states for one user. The server-side key is secret, because it can download the whole environment document, including every segment rule and override. Keep it in a secrets manager. Administrative tokens, used to change states by script, are the most powerful of all and must be guarded like a production database password.

Do not store secrets in values

A state’s value may travel to many systems, and can appear in logs, caches, and analytics tools. Passwords, tokens, and private addresses belong in a secrets manager. Use values for behaviour and harmless settings.

Privacy of identities and traits

Identities and traits can contain personal information. Send only what your rules truly need, use opaque identifiers instead of names and email addresses, and send traits such as plan or country rather than sensitive facts. Running Flagsmith on your own servers keeps personal data under your control, which can help with laws such as the European GDPR or India’s data protection law. With local evaluation, identity details can stay inside your own servers while only the rules are downloaded.

Governance habits

• Keep the audit log. Many compliance rules require proof of who approved Production changes.
• Review access regularly. Every few months, remove permissions nobody needs.
• Use single sign-on. People should lose access when they leave the company.
• Separate duties. The person who proposes a critical change should not be the only one who approves it.
• Plan break-glass access. Define a documented emergency path for setting a state to its safe position quickly, with review afterwards.

If states change what users see, you must watch the effect of every change, and watch the states themselves for things that look wrong.

Tag signals with the state

The most useful habit is to record which state a request ran with. Then any graph can be split into two lines: users with the capability and users without. The question “is the new checkout slower?” becomes a comparison of two lines. Flagsmith can send state information to analytics and monitoring tools through integrations, and many teams also add the state to their own logs.

Guardrail metrics

When a rollout starts, a team writes down guardrail metrics, numbers that must not get worse no matter how good the new capability looks: error rate, slowest-request time, payment success, app crashes, and support contacts. If any guardrail crosses its limit, the rollout pauses or reverses.

flowchart TB
    A["Change state to next step in Production"] --> B["Webhook posts to team channel"]
    A --> C["Audit log records the change"]
    A --> D["Applications receive the new state"]
    D --> E["Metrics tagged with environment and state"]
    E --> F{"Guardrails healthy?"}
    F -->|"Yes"| G["Wait, then continue to next step"]
    F -->|"No"| H["Alarm fires"]
    H --> I["Set state back to previous version"]
    I --> J["Investigate with logs and traces"]
    

Detecting drift

Drift is the slow growth of unexplained differences between environments. To catch it, compare environments before every release, listing features whose states differ and explaining each. Some teams write a short script that fetches the states of two environments through the Admin API and prints the differences. Others keep the intended states in files and compare them with the real ones on a schedule, raising an alarm when they disagree.

Looking for states that no longer matter

• Features unchanged for months. A state that has been fully on or fully off for a long time may no longer provide any safety or choice.
• Orphaned overrides. Identity overrides for users who left, and segment overrides for segments that no longer exist, are noise.
• States with no readers. Evaluation counts, where your plan offers them, show features no one reads any more.
• Staging differing from Production without a reason. This is the most common sign of a misleading rehearsal.

Watch the plumbing too

Monitor how often SDKs fail to reach Flagsmith, how old the states held in each server are, and how often applications fall back to defaults. A rising number of fallbacks is an early warning that something is wrong between your applications and the flag service, long before users complain.

A state is read on almost every request, so at the scale of a large company, even small delays and rare failures matter.

Keep reads cheap

If every read needed a trip across the internet, a page with twenty features would feel slow. The standard approach is to fetch once, keep the answers in memory, and refresh in the background. Back-end servers use local evaluation so that each read takes only a tiny slice of time. Browsers and apps fetch at the start of a session and reuse the answers.

Keep the data lean

The size of an environment’s data grows with the number of features, segments, and overrides. A large environment document means a bigger download and more memory on every server. Tidy habits keep it light: delete finished features, remove unused segments, and avoid thousands of identity overrides when one segment rule would do.

Designing for failure

Mobile apps and old versions

Once an app version is installed on a phone, its code cannot change until the person updates. A feature state is therefore a remote control for capabilities already inside the installed app. You can set a faulty capability to its safe state on millions of phones without waiting for an app store review. But states for code that does not exist in older versions need care, so segment rules often include a condition on the app version.

A pattern is a proven solution to a repeating problem. An anti-pattern is a tempting solution that causes trouble. Learn both.

Patterns worth adopting

Anti-patterns to avoid

These habits come from many teams learning the hard way. Following them saves you from most of the pain.

Best practices

• Create features disabled. Enable their states deliberately, starting in Development.
• Know the layers. Identity overrides beat segment overrides, which beat the environment default. Check all three when debugging.
• Decide how enabled and value combine. Write the rule once, put it in one helper in your code, and validate values before use.
• Write the off behaviour in the description. A stranger should know what users see when the state is disabled.
• Prefer segments over personal overrides. Rules scale and can be explained.
• Always supply safe defaults in code. The default should be the old, proven behaviour.
• Mirror Staging to the next Production state. Make the rehearsal predict the performance.
• Compare environments before each release. Explain every difference or fix it.
• Release in small steps with guardrails. Employees, beta, a percentage, then everyone, watching the numbers at each step.
• Review critical Production changes. A second pair of eyes is cheap protection.
• Add a reason to every Production change. A short note makes history readable.
• Announce Production changes in a shared channel. Visibility makes investigations faster.
• Practise the safe state. Nobody should see the off position for the first time during an emergency.
• Clean up overrides and features. Remove personal overrides, unused segments, and finished features regularly.
• Describe states as code when they grow. Repeatable beats hand-clicked.

Common mistakes

A checklist before changing a Production state

It also helps to talk openly about culture. States work best in teams where setting something back to its safe position in Production is treated as a normal, healthy action and not as a failure to be hidden. If people fear blame, they will hesitate to reverse a bad change, and the greatest strength of a state, its speed, is wasted. Teams that celebrate a quick, calm reversal, and then study it without blame, become safer over time.

The idea of controlling exposure through changeable state, in careful steps, is common to the best-known engineering organisations. Here are public lessons, followed by an illustrative story.

An illustrative story: a bank app and a new transfer screen

The following story is invented, shown to tie the ideas together. A bank has a Flagsmith project with Development, Staging, and Production environments. A developer creates a feature called “instant_transfer_v2.” It is created disabled in every environment, with a description that says what the screen does, who owns it, and that the off behaviour is the old transfer screen.

Patterns in all these stories

Short, clear answers to questions that beginners and experienced engineers often ask about feature states in Flagsmith.

You have travelled from the fear of changing a live product to the calm of small, reversible, recorded changes of state. Here is what to remember.

A feature state in Flagsmith is the small stored answer that tells your application what to do: whether a feature is enabled, what its value is, and which variation a person receives. It lives inside an environment, and it is stacked in layers, so that one feature can give a different answer to a single user, a group, or everyone. Changing a state is quick, recorded, and reversible, which is what turns risky releases into calm experiments. The practical habit to carry away is to always ask three questions before touching any state: in which environment am I, for whom does this change apply, and what is the safe position I can return to?