The phrase is used in several ways, and mixing them up is the number one source of confusion. This chapter separates them.

First, the basics

A feature flag is a switch inside software that decides whether a behaviour is active. Flagsmith is a platform that stores those switches, lets people change them from a dashboard, and delivers the answers to applications through small libraries called SDKs. A value is an optional piece of information that a flag can carry along with its on or off state, such as a number or a short piece of text. That is called remote configuration.

The word “default”

A default is the answer used when no more specific answer exists. In everyday life, the default font in a document is what you get if you do not choose another one. In Flagsmith there are four distinct defaults, each living in a different place and used at a different moment.

Defaults rarely get attention, because when they work nobody notices. They matter most on the days everything else is going wrong.

The problem defaults solve

Every system must decide what to do in situations nobody planned for. A flag platform is a network service, and network services are sometimes slow, sometimes unreachable and sometimes asked for things that do not exist. If your application has no plan for these moments, it will invent one by accident: it may crash, it may show a blank screen, or it may quietly turn a feature on that should have been off. A deliberate default turns an unpredictable accident into a predictable, harmless behaviour.

A principle older than the internet

In 1975, two computer scientists, Jerome Saltzer and Michael Schroeder, published a famous paper on protecting information in computer systems. One of their design principles is called fail-safe defaults. It says that when something goes wrong or is unspecified, the system should lean towards the safe outcome rather than the permissive one. A door that cannot reach its lock controller should stay locked, unless it is a fire exit, in which case it should open. The principle is not “always choose off”. It is “choose the answer that causes the least harm”.

What big companies teach us

Engineering teams at companies such as Netflix and Amazon have spoken publicly about designing for failure: assuming that any dependency can be slow or unavailable and making sure the customer still gets a reasonable experience. Netflix is widely known for the idea that a missing recommendation row should never stop a video from playing. A flag lookup is one more dependency. If it fails, the product should drop back to a calm, known behaviour and carry on.

The cost of an unthought default

An unthought default rarely announces itself. It sits quietly in the code for months, and then one afternoon a network problem or a typo causes it to be used. The cost is not the moment of failure but the confusion afterwards: the team asks why customers saw something nobody planned, and nobody can say who decided it. Writing the decision down in advance, even in one sentence, turns that confusion into a lookup. The effort is small, the benefit arrives on the worst day of the year, and that is the best kind of engineering trade.

A picture of the whole journey makes each individual default easier to place.

Follow a feature from the moment it is created to the moment a user sees its result. The creation default sets the starting state. Each Environment then holds its own baseline, which is the Environment default. Segment and identity overrides may change the answer for chosen people. And if the application cannot obtain an answer, it uses the default written in its own code.

flowchart TD
  A["Feature created with a creation default"] --> B["Each Environment holds its own baseline value"]
  B --> C{"Does the user have an identity override?"}
  C -- Yes --> R1["Answer: identity override"]
  C -- No --> D{"Does the user match a segment override?"}
  D -- Yes --> R2["Answer: segment override"]
  D -- No --> R3["Answer: Environment default"]
  R1 --> E["SDK delivers the answer to the app"]
  R2 --> E
  R3 --> E
  E --> F{"Did an answer arrive?"}
  F -- Yes --> G["App uses the answer"]
  F -- No --> H["App uses the default written in its code"]
    

Which default answers which question?

A quick way to keep the four straight is to attach a question to each. The creation default answers “what should this feature start as?” The Environment default answers “what is the general rule in this stage?” The control value answers “what does the ordinary user get while an experiment runs?” The default in code answers “what do we do if nobody answers at all?” If you can state which question you are asking, you almost always know which default you mean.

When you create a feature, Flagsmith asks what it should start as. That small decision is copied into every stage at once.

What you decide at creation

When creating a feature in a Project, you give it a name and a description, and you typically choose whether it should be enabled or not by default, and, for features that carry a value, what that starting value is. Because a feature’s definition is shared across the whole Project, Flagsmith needs to put a state into every Environment, and by default it uses what you entered on the creation form.

The effect on every Environment

If you create a feature and choose to enable it by default, then Development, Staging and Production can all receive the feature switched on. That may be exactly what you want for a harmless setting. It is a serious problem for a new, untested checkout page, because the moment the feature is created, real customers in Production could see it.

graph TD
  FORM["Creation form: enabled by default = yes, value = 20"] --> DEV["Development: enabled, value 20"]
  FORM --> STG["Staging: enabled, value 20"]
  FORM --> PRD["Production: enabled, value 20"]
    

A safety setting at the Project level

Because this behaviour can surprise people, many versions of Flagsmith offer a Project setting, often described as preventing flag defaults. When it is switched on, the starting state and value entered at creation are not spread across all Environments, which keeps new features switched off in places where nobody chose otherwise. The exact wording and availability may differ in your version, so open your Project settings and read the description there before relying on it. If it exists in your version, switching it on is one of the quickest safety wins in the whole product.

A short story of a creation default gone wrong

Imagine an engineer creating a flag for an unfinished loyalty page. In a hurry, they tick the option to enable it by default. Because the feature definition is shared by every Environment, Production receives the flag in the enabled state a moment later. The page code is deployed and waiting, so real customers suddenly see half a page. Nothing was “flipped” in Production by any person. The creation form did it. Stories like this are why many teams treat creation as a safe, boring event, and keep every real decision for the later, deliberate step of enabling the flag in each Environment.

This is the default most people mean in daily work: the baseline answer a feature gives inside one Environment.

What it is

Inside each Environment, every feature has a feature state: whether it is enabled, and, if it carries one, its value. That state is the Environment default. It is the answer given to anyone who does not match a segment override or an identity override. Think of it as the general rule for that stage, with overrides as the exceptions.

Why it is the most important default

For most users, the Environment default is the answer. If only staff and a pilot group have overrides, then everyone else, perhaps ninety-nine percent of customers, simply gets the Environment default. Changing it changes the experience of nearly everybody at once. That is why it deserves the strongest protection in Production.

Notice the shape of a classic rollout: the Environment default stays off while overrides grow the audience, and the very last step is to change the default itself to on. Because that last step affects everyone, it is the one to take most carefully and to announce in your team channel.

The value half of the default

For features that carry a value, the Environment default includes that value. A search feature may be enabled with the value “twenty” in Production and “five” in Development, so test runs stay small and quick. Each Environment keeps its own copy, so changing the value in one never touches another.

Reading defaults in the dashboard

In the feature list, each row typically shows the current state for the Environment you are looking at, along with a hint when overrides exist. Make it a habit to open the same feature in two Environments side by side, and compare the state and the value. If you only ever look at one Environment, drift can grow unseen. A good time for the comparison is the day before a launch, and again straight after any incident in which values were changed by hand.

A flag can carry more than yes or no. When it carries a number or a piece of text, the question of a good default becomes richer.

What is a value?

A value is information attached to a feature, such as a whole number, a piece of text or a true or false answer. Using values lets teams change settings of a running application without releasing new code. This is called remote configuration. Examples include the number of results on a page, the text of a banner, or the maximum size of an upload.

An empty value is also a value

A feature may have no value at all. Your code must handle that case sensibly. An application that expects a number and receives nothing might treat the missing number as zero, and zero can mean “show no results”, “allow no uploads” or, in some designs, “no limit at all”. The meaning of zero and of empty is one of the most common sources of surprise, which is why the next chapters spend time on it.

This is the default that protects you on the worst day. It lives outside Flagsmith, in the application that asks the question.

What it is

When an application asks the SDK for a flag, three outcomes are possible. The SDK returns an answer. The SDK returns a built-in “nothing found” answer. Or the call fails. For the second and third outcomes, the application needs its own plan. The default in code, also called the fallback or safe default, is that plan. It is written by the developers and shipped inside the application.

How SDKs help

Most Flagsmith SDKs return a harmless built-in answer when a flag is missing or Flagsmith cannot be reached, typically “not enabled” for a flag and “no value” for a setting. Many SDKs also let you supply your own default flag handler, which is a small piece of logic that decides what to return in such cases, flag by flag. The exact behaviour differs between languages and versions, so read the notes for the SDK you use. The principle never changes: never leave this to chance.

Where to place defaults in the code

Resist the temptation to scatter defaults wherever a flag is used. A tidy approach is to collect every flag name and its default in one small section, often called a flag catalogue. The rest of the code asks the catalogue for a flag and receives both the live answer and, if needed, the fallback. This brings three advantages: names are written only once, a reviewer sees any default change in one place, and the unreachable test can exercise every default by switching the catalogue to fallback mode.

When a feature splits users between versions, the word default takes a slightly different shape.

What is a multivariate feature?

A multivariate feature offers several possible values and divides users between them by percentage. It is the base of experiments. A button might say “Buy now” for some people, “Get it today” for others and “Add to basket” for the rest. Each alternative is called a variation.

The control

The original value of the feature is called the control. It is the version that people receive when they are not placed in any variation. Each variation is given a percentage of users, and whatever percentage remains unassigned falls back to the control. If two variations take twenty percent each, the control serves the remaining sixty percent. In this sense, the control is the default of an experiment.

Why a good control matters

If the control is the long-standing, well tested value, then an experiment that goes wrong harms only the small share placed in a variation. If the control itself is something untested, there is no safe place to retreat to. Always keep the proven version as the control, and move it only after a challenger has clearly won.

Pitfalls with the control

Two mistakes recur. The first is editing the control value in the middle of an experiment. Everyone in the control group suddenly receives something different, and the comparison with the variations is spoilt. Decide the control before the experiment begins and leave it alone. The second is forgetting that the control also serves anyone left unassigned. If the variations take only ten percent between them, ninety percent of users, including all anonymous visitors, receive the control, so it must be an experience you are happy for most people to have.

When several rules could apply, Flagsmith has a clear order. Knowing exactly where the default sits in that order removes most guesswork.

For one feature, in one Environment, for one person, Flagsmith works from the most specific rule to the most general. It checks for an identity override first, which is a rule for one exact person. Next it checks segment overrides, which are rules for groups, taking the highest ranked one that matches. If neither applies, the answer is the Environment default. Only if the application receives no answer does the default in code take over.

flowchart TD
  START["Question: value of feature X for person Y in Environment E"] --> Q1{"Identity override for Y?"}
  Q1 -- Yes --> R1["Use identity override"]
  Q1 -- No --> Q2{"Segment override that matches Y?"}
  Q2 -- Yes --> R2["Use highest ranked matching segment"]
  Q2 -- No --> R3["Use the Environment default"]
  R1 --> OUT["Answer returned"]
  R2 --> OUT
  R3 --> OUT
  OUT --> Q3{"Did the app receive it?"}
  Q3 -- No --> R4["Use the default in code"]
  Q3 -- Yes --> DONE["Use the answer"]
    

A debugging ladder for a surprising answer

When a person sees an answer nobody expected, walk down the same ladder Flagsmith does. Do it in order, and write the finding at each step.

• Which Environment was asked? Confirm the key belongs to the stage you think it does.
• Was an identity sent? If not, only the Environment default can apply.
• Is there an identity override? Look at the person’s page in the dashboard.
• Which segments match? Check traits and their exact format, then the order of the segments.
• What is the Environment default? Compare it with the answer received.
• Did the answer arrive at all? If the answer matches none of the above, the application may have used its own default.

Many answers depend on who the person is. What happens when you do not know?

Identities and traits

An identity is Flagsmith’s name for one end user, usually represented by a user ID. A trait is a fact attached to an identity, such as “plan equals premium” or “country equals India”. A segment selects identities by their traits or by a percentage. These need information about the person to work.

When the person is unknown

A visitor who has not signed in has no user ID. If the application asks for the Environment’s flags without an identity, no segment rule can match, and the visitor receives the Environment default. The same happens if the application asks with an identity but never sends the trait a segment needs. A segment for “country equals Germany” simply cannot match a person whose country was never reported.

The moment a visitor signs in

A person often starts as an anonymous visitor and becomes a known user partway through a visit. Before sign-in, they receive the Environment default. After sign-in, segments and overrides may change some answers. If a feature suddenly switches on or off the moment someone logs in, the screen may jump in a way that feels strange. Plan for this by keeping the pre-login experience simple, and by refreshing flags once, calmly, straight after sign-in rather than letting values change in the middle of a task.

There is no universal answer, such as “always off”. There is a short method that works for any flag.

Write the reasoning in the description

A default is only half a decision without its reason. Put one sentence in each flag’s description, so that the next person understands without asking. Useful descriptions read like this: “Off by default, because the old payment sheet is proven and failing back to it is harmless.” Or: “On by default, because losing this check during an outage would let large fraudulent transfers through.” Descriptions like these also teach new engineers how the team thinks, and they are far more helpful than “controls the new thing”.

Two famous phrases from engineering describe opposite leanings. Both are correct, in different situations.

Fail-safe and fail-open

A system that is fail-closed (also called fail-secure) stops or denies when something goes wrong. A bank vault door stays shut if the power fails. A system that is fail-open allows or continues when something goes wrong. A fire exit door swings open if the power fails, because trapping people is worse than letting someone through. Which is right depends entirely on what the danger is.

Notice that “off” is not always the safe answer. A flag that enables a protection is safest when its default is on. A flag that enables a risky new behaviour is safest when its default is off. The skill is to ask, for each flag, which direction protects people and the business.

When the answer is mixed

Some flags guard behaviour where both directions carry a cost. A recommendation panel may slow the site if it runs during a traffic peak, yet hiding it may cost sales. In such cases, decide in advance what matters most for the situation in which the default will be used, and note it. If the default is used because Flagsmith is unreachable, that is usually a moment of general trouble, and lighter behaviour tends to be wiser. Writing “when in trouble, lighter is better” in the description gives future engineers a rule they can apply to similar flags.

Practitioners sort flags into a handful of kinds. Each kind has a natural default, which saves thinking from scratch every time.

The kinds, briefly

Release flags hide unfinished work and are short lived. Experiment flags compare versions with real users. Operational flags let engineers change system behaviour under stress. Kill switches turn a risky feature off in an emergency. Permission flags give certain customers or staff special access. This classification has been popularised by engineers writing on well known software design sites.

Values look simple, yet they hide the most surprising default bugs. A little discipline in code prevents nearly all of them.

The zero trap

When a number is missing, many programming languages quietly treat it as zero. Zero might be harmless, or it might change meaning completely. A “maximum items in basket” of zero could mean customers cannot buy anything. A “retry limit” of zero could mean never try again. A “timeout” of zero could mean wait forever. The same quiet zero can be a disaster in one place and invisible in another.

Units matter

A value of “five” is meaningless without a unit. Is that five seconds, five minutes or five hundred milliseconds? If one team writes the value thinking in seconds and the code reads it as milliseconds, the feature misbehaves in a way that looks like a mystery. Put the unit in the feature’s name and description, for example “partner_timeout_seconds”, so nobody has to guess.

Defend your code

Treat every value that comes from Flagsmith the same way you would treat input from a stranger. Check that it exists, check that it is the type you expect, and check that it lies within a sensible range. If it fails any check, use the default in code. This habit is sometimes called clamping: forcing a value to stay between a lowest and highest acceptable number.

True and false stored as values

A feature can carry a value that is itself the text “true” or “false”, or a true and false type. This is a different thing from the enabled state of the feature. A feature may be enabled with a value of false, which the code must read as “feature on, setting off”. When values and states disagree, a missing value could be read either way, depending on the language. If you need a yes or no answer, use the enabled state, and keep values for numbers and text. If you must store a boolean value, give the default in code explicitly and name the feature so the meaning is obvious.

It helps to list every situation in which a default takes over, so none comes as a surprise.

Notice that some defaults are part of normal life, such as the Environment default for ordinary users, while others are emergency measures, such as the default in code. Both deserve care, but the second kind deserves it before the emergency, because there will be no time to think during one.

Between a fresh answer and a default sits a third possibility that is often better than either: the last answer you remember.

Fresh, remembered, or default

Most SDKs keep a copy of the flags they last received, either in memory or, for mobile and browser apps, in local storage on the device. If a later request fails, a well designed SDK can carry on with the last known values instead of falling all the way back to the default in code. This is usually a better experience, because the last known values were chosen by a person and reflected the real state of the business a moment ago.

flowchart TD
  A["App needs flag value"] --> B{"Can SDK fetch fresh values?"}
  B -- Yes --> C["Use fresh value"]
  B -- No --> D{"Does SDK hold earlier values?"}
  D -- Yes --> E["Use last known value"]
  D -- No --> F["Use default in code"]
    

Why this matters for the default you choose

The default in code is used only when the first two options fail. That happens most often when an application starts for the very first time with no connection, or when its stored copy has been cleared. Because those moments are rare but serious, the default should still be chosen with care, even if you expect to use it seldom.

How old is too old?

Last known values are helpful, but they do age. A value remembered from an hour ago is almost always still right. A value remembered from last week might not be, especially if a kill switch has been flipped since. Teams usually set a maximum age for stored values, after which the application prefers its coded default to a stale memory, or tries harder to refresh. The right age depends on how quickly your flags change and how much harm a stale value could do. For flags that guard safety, shorter is wiser.

Environments are born with defaults too, and the way they are created affects everything that follows.

A new Environment starts somewhere

When you add an Environment to a Project, it needs a state for every existing feature. Depending on how it is created, that state may come from a basic blank starting point, or from a copy of another Environment. Flagsmith lets you create a new Environment by cloning an existing one, which copies its states and values. This is the quickest way to start a new Staging or regional Environment from a known good set of values.

Drift: the slow divergence

Once separate, Environments drift. Someone changes a value in Production during an incident and forgets to match Staging. Weeks later a test passes in Staging and fails in Production, because their defaults are no longer alike. Regular side by side comparison, especially before launches, catches drift early.

Regional Environments and local defaults

Some products add an Environment for a particular region, for example one for a country with different laws or payment methods. Its defaults are likely to differ from the global Production Environment, and that is fine, provided the differences are deliberate and written down. A short table listing which values differ between a regional Environment and Production, and why, saves the next engineer from “fixing” a difference that was important.

The most irritating bugs around defaults are the ones where nothing visibly goes wrong. The default simply keeps being used.

How silent defaults happen

A flag lookup is made by name. If the name in code does not exactly match the name in Flagsmith, the lookup finds nothing, and the default quietly takes over. This can happen through a simple typo, a difference in capital letters, an extra space, a rename in the dashboard, or a deletion. The code does not crash, because defaults are designed to avoid crashes. The feature just never turns on, and engineers lose hours wondering why a flag that is clearly enabled has no effect.

Making silent defaults loud

The best protection is to turn silence into a signal. When the application asks for a flag that exists in its shared list but receives the default because the flag was not found, write a log message or increase a counter. A graph of “defaults used” that suddenly rises tells you that names or connections are broken long before customers complain.

The same audience can be reached in two opposite ways, depending on which side the default is placed. Each has a natural use.

Pattern A: default off, exceptions on

The Environment default is off, and chosen groups are switched on through segment overrides. This is the classic rollout. The feature starts invisible, staff see it first, a pilot group next, a percentage after that, and finally the default itself is switched on. It is the safest pattern for new features, because anything not mentioned is unaffected.

Pattern B: default on, exceptions off

The Environment default is on, and chosen groups are switched off. This suits a feature that is already live for everyone, where you need to hold it back from a few people, for example customers in a country where a law forbids it, or a partner with an older integration that cannot cope. It also suits the “kill for one group” case: leave the feature on for most, and quickly switch it off for the one segment where a problem appears.

flowchart LR
  subgraph PA["Pattern A: default off"]
    A1["Environment default: Off"] --> A2["Staff segment: On"]
    A1 --> A3["Ten percent segment: On"]
    A1 --> A4["Everyone else: Off"]
  end
  subgraph PB["Pattern B: default on"]
    B1["Environment default: On"] --> B2["Restricted country segment: Off"]
    B1 --> B3["Legacy partner segment: Off"]
    B1 --> B4["Everyone else: On"]
  end
    

Moving from Pattern A to Pattern B

Many features travel through both patterns in their lifetime. They begin as Pattern A, with the default off and groups added. When the feature reaches everyone, the default is switched on, and the remaining overrides are removed. Later, if a particular group must be excluded, a segment override for that group is turned off, which is Pattern B. At each hand-over, check that no old override is left behind pointing the wrong way. A stray “on” override for staff is harmless once the default is on, but a stray “off” override can quietly hide the feature from a group for months.

A percentage rollout gives different answers to different people at the same time. The default plays a quiet but important role.

How the default and the percentage work together

A percentage segment selects a share of identities, such as ten percent of all users. A segment override then gives those people a different answer from the default. Everyone outside the percentage receives the Environment default. So at “ten percent”, ninety percent of users are, in effect, served by the default. This is why the default must be a good experience in its own right, because it is the experience of the large majority during most of a rollout.

Steady groups

The split is steady for each identity. Flagsmith works out a position for each person from their identity, so the same person stays in the same group as the percentage widens. Someone in the first ten percent remains included at twenty-five percent. No person flickers between two experiences. This steadiness only works for people with an identity. An anonymous visitor with no identity cannot be placed in a percentage and therefore always receives the default.

With ten flags, you can remember every default. With a thousand, you need a system.

Keep names and defaults in one place in code

Instead of scattering flag names and their default values across many files, collect them in one shared section of the code. Each entry states the flag name and the default for it. A developer who needs a flag finds it there, and a reviewer sees any change to a default at a glance. This also protects against typos, because a name is written once.

Keep a human register too

In your team’s documents, keep a short table listing each important flag, its kind, its default in code, the reason for that default and its owner.

Review defaults when code changes

Whenever a pull request adds a flag or changes a default, make it a standing question in the review: what happens if the answer never arrives? A reviewer who asks this one question prevents a surprising number of incidents.

A checklist for code review

• Is the flag name taken from the shared catalogue, not typed by hand?
• Is there an explicit default, and does it lean towards the smaller harm?
• Is the reason for the default written in the flag’s description?
• If the flag carries a number or text, is the value checked for type and range?
• Is there a test with the flag on, off, and with no answer?
• Does the default agree with the Environment default, or is the difference explained?

A default that has never been exercised is a guess. Testing turns it into a promise.

The unreachable test

The most valuable test is also the simplest: run the application, in a test setting, with Flagsmith deliberately unreachable. Start it with no connection, with a wrong key, or with the network blocked, and watch what happens. Every important screen should still work, using its defaults. If something breaks, you have found a missing or careless default while the stakes are small.

The three states of every flag

For each flag, test three situations. With the flag on, the new behaviour works. With the flag off, the old behaviour works. With no answer at all, the default works. Most teams remember the first two and forget the third, which is exactly the situation the default exists for.

Changing an Environment default in Production is among the most powerful actions in Flagsmith, because it affects everyone not covered by a special rule.

Why it needs care

An override changes the experience of a chosen group. The Environment default changes the experience of everybody else, which is usually most of your users. Flipping it in Production is therefore the equivalent of a release to the whole population, and should be treated with the same seriousness as deploying code.

Layers of permission

Flagsmith controls access at the Organisation, Project and Environment levels. Creating features, and thereby setting the creation default, is a Project-level permission. Changing an Environment’s feature state, which sets the Environment default, is an Environment-level permission. Give the first more widely, and the second only to a small, trained group for Production. Where your plan offers change requests, require a second person’s approval before a Production default changes, so that one slip cannot affect every customer.

Defaults are decisions about what happens by accident. That makes them a security topic.

Permissive defaults are a risk

A default that grants access, for example enabling a premium tool when no information is available, is a standing invitation for mistakes to become leaks. The principle of fail-safe defaults says the opposite: when in doubt, deny, unless denial itself is dangerous. For flags that gate capabilities, choose defaults that give nothing away.

Defaults are visible to clients

Anything sent to a browser or phone can, in principle, be read by the user. That includes flag names and values. Do not put secrets, internal code names or private comments in values or descriptions that clients can read. Where your version offers the option, hide disabled flags from client applications, so people cannot discover the names of unannounced features.

A flag is not a lock

A flag decides what the interface shows. It does not protect the data behind it. Anything that really must be protected needs a permission check on your own servers, whatever the flag or its default says. A default of “off” that hides a button does not stop a determined person from calling the underlying service directly.

Do not store personal data in values

Because values travel to client applications, never place personal data, private email addresses or customer lists inside a flag value or a trait you do not need. A value should be a small setting, not a record. If you must target by a personal fact, send a minimal derived trait, such as a plan name or a region, rather than the raw data, and follow your company’s rules on privacy.

The cure for a silent default is to make it speak.

What to measure

Three simple measures give real insight. The default usage count is how often the application fell back to a default in code, per flag. The missing flag count is how often it asked for a flag that does not exist. The fetch failure count is how often it failed to reach Flagsmith at all. In a healthy system all three are close to zero, and any sudden rise deserves a look.

Putting it on a graph

Send these counts to the monitoring tool your team already uses, such as Datadog, and place flag changes on the same graph by using the integration that announces them. When defaults-used jumps up right after a deployment, you know a name was mistyped. When fetch failures jump at the same time as a platform incident, you know the app is running on last-known values. The audit log of Flagsmith records who changed what and when, which completes the story.

These traps appear in almost every company that adopts feature flags. Learn them now and avoid paying for them later.

More small mistakes worth naming

• Never testing the application with Flagsmith unreachable.
• Using zero as a quiet default for numbers that mean limits or times.
• Letting Staging and Production defaults drift apart.
• Reusing a flag name for a new purpose, so old code reads a default that no longer fits.
• Not counting how often defaults are used.

Things will go wrong. Teams that planned their defaults recover in minutes, and teams that did not recover in hours.

Scenario one: Flagsmith is unreachable during a launch

Applications serve last known values where they have them, and defaults in code where they do not. If defaults were chosen well, customers see the old, proven behaviour and the launch simply pauses. Once the platform returns, the flags apply as planned. After the incident, review how many users fell to defaults and whether any default was wrong.

Scenario two: a feature never turned on, though the flag is enabled

Check three things in order. Is the application using the correct Environment key? Does the flag name in the code match exactly the name in Flagsmith? Has the app refreshed its values since the change? Most “it does not work” reports end at one of these. The counter of missing flags makes the second check instant.

Scenario three: a Production default was changed by mistake

Restore the previous value first, which the audit log shows. Customers come before investigation. Afterwards ask how a person with permission came to flip the wrong Environment, and consider approvals and clearer Environment names.

Scenario four: a numeric value was mistyped

A value of two thousand where twenty was meant should have been rejected by the range check in code. If it was not, correct it in the dashboard at once, then add the missing range check so the next typo is harmless.

Scenario five: premium features vanished for paying customers

Scenario six: a flag was deleted while code still used it

The application falls back to its default, which is why defaults matter. Recreate the flag with the same name, restore its states from the history, and plan a proper removal from code before deleting it again.

After any incident: three questions for the review

Once the pressure is off, hold a short, blame-free review. Ask three questions about defaults. Which defaults were actually used, and for how long? Did each one behave as the register said it would? And is there any flag where the default surprised us? Write the answers on one page, update the register, and fix any default that proved wrong. Over a year, a team that does this builds a register that is accurate because every incident has sharpened it.

Defaults are also what let a flag system serve millions of users without becoming a weak link.

Do not wait forever for an answer

Any network call can be slow. If an application waits for Flagsmith before showing a page, a slow answer becomes a slow page. Good applications set a short timeout, which is a limit on how long to wait, and use the default if the answer has not arrived. A timeout of a few hundred milliseconds for a page-critical flag is common, while background refreshes can wait longer.

Start fast on a cold start

A cold start is when an application launches with nothing remembered. Mobile apps opened for the first time, and servers freshly started, are cold. During a cold start there are no last known values, so the default in code is what the first screen uses. Many teams make the first screen independent of flags where possible, and let flags refine later screens, so the cold start is quick and calm.

Cache and local evaluation

Fetching flags on every check would be slow and costly. SDKs keep flags in memory and refresh on a timer. Some server SDKs offer local evaluation, downloading the complete rule set once and deciding flags inside your own server in microseconds. In this mode the platform is not asked for each decision, so even a long outage affects only how fresh the rules are, not whether decisions can be made.

flowchart LR
  U["Millions of users"] --> APPS["Your application servers"]
  APPS --> SDK["SDK with local cache"]
  SDK -- "periodic refresh" --> PROXY["Optional local proxy"]
  PROXY -- "occasional sync" --> FS["Flagsmith platform"]
  SDK -. "if nothing available" .-> DEF["Default in code"]
    

Choosing timeouts for different kinds of flag

Ideas become clear when applied. Follow the team at a fictional retailer, Northwind, as they decide every default for four flags.

The situation

Northwind sells goods through a website and a mobile app. A team of about twenty people works on both. They are preparing four flags for the coming sale season: a new payment sheet, a limit on search results, a large transfer safety check, and an advanced export tool for business customers. For each, they walk through the same questions from Chapter 11.

The steps they followed

The result on sale day

During the sale, a short network problem prevents some mobile apps from refreshing flags. The apps use last known values. A few brand new installs with no stored copy use the coded defaults: the old payment sheet, twenty results, the safety check on and the export tool off. Customers shop normally. The “defaults used” graph rises for twenty minutes, then falls. Engineers read the graph, confirm that all defaults behaved as designed, and write a short note. Nobody is woken at night.

Few teams start from nothing. If flags already exist, a short audit can find the weak defaults before an incident does.

Quick wins in one afternoon

If time is short, three small actions give most of the benefit. First, switch on the Project setting that stops creation defaults spreading, if your version offers it. Second, find every flag that guards money, personal data or a protection, and give each an explicit default in code. Third, add a single counter for defaults used to your monitoring tool. These three steps take hours, not weeks, and they catch the failures that hurt most.

Having several layers of default is a design choice with real benefits and real costs.

The central trade-off: conservative or helpful

A very conservative default, such as “hide every new thing”, is safe but may keep customers from benefits. A very helpful default, such as “show everything available”, is generous but exposes unfinished or risky behaviour. There is no single right point. The method in this guide is to choose per flag, according to which failure hurts more, and to write the reasoning down.

When defaults are not the right tool

A default is a fallback, not a business rule. If something must be true by law or contract, such as showing a required notice to customers in a certain country, relying on a flag default is fragile. Such rules belong in code or in a controlled data store with proper review. Flags and their defaults are best for behaviour that changes often and can safely fall back.

A word on teams and habits

The technical side of defaults is small. The habit side is large. A team that asks “what is the default?” in every design review and every code review will rarely be surprised. A team that never asks will be surprised repeatedly, and each surprise will feel like bad luck rather than a missing question. If you adopt only one habit from this guide, make it the single question: if the answer never arrives, what do we want to happen?

A short list to keep nearby. If you do these ten things, you will avoid most of the pain described in this guide.

Making the checklist stick

Lists on their own fade from memory. Turn the ten points into a short template that is attached to every new flag’s ticket, so each point is answered while the flag is being created rather than remembered later. Review the template twice a year, and drop any item that never changes an outcome. A checklist of six living questions beats a checklist of twenty that people tick without reading.

Keep this table nearby while reading documentation or talking with your team.

Quick answers to the questions that come up most often.