Before listing mistakes, it helps to understand why smart people keep making them. The causes are surprisingly human.

A quick refresher on flags

A feature flag is a named switch that lives outside your program. Your application asks, “is this feature on?”, and a flag service such as Flagsmith answers. Because the answer comes from the service, you can change behaviour in seconds without releasing new code. Flagsmith organises flags in layers: an organisation contains projects, a project contains environments such as development, staging and production, and each environment keeps its own state for every feature. Applications talk to Flagsmith through small code libraries called SDKs, using keys that identify the environment.

Why flags invite mistakes

The three families of mistakes

Nearly every flag mistake belongs to one of three families. Human mistakes happen at the dashboard: wrong environment, careless changes, unclear names. Design mistakes happen in the code: no defaults, tangled flags, secrets in values. Process mistakes happen in the team: no owners, no cleanup, no review. Knowing the family helps you choose the right remedy, because a human mistake is fixed with guardrails, a design mistake with better code and a process mistake with better habits.

Before we visit each mistake in detail, here is a map showing where they live and how they connect.

flowchart TB
    M["Common Flagsmith Mistakes"] --> H["Human at the dashboard"]
    M --> D["Design in the code"]
    M --> P["Process in the team"]
    M --> O["Operations and hosting"]
    H --> H1["Wrong environment"]
    H --> H2["Vague names and empty descriptions"]
    H --> H3["Changing many things at once"]
    D --> D1["No default values"]
    D --> D2["Wrong or leaked keys"]
    D --> D3["Secrets in flag values"]
    D --> D4["Tangled and nested flags"]
    D --> D5["Unstable identities"]
    P --> P1["Flags never removed"]
    P --> P2["No owners or end dates"]
    P --> P3["Too-fast rollouts"]
    P --> P4["Loose permissions"]
    O --> O1["No backups or restore drills"]
    O --> O2["Unmonitored task processor"]
    O --> O3["Skipped upgrades"]

Reading the map

The map has four branches. The human branch covers what happens at the dashboard: acting in the wrong environment, writing unclear names and changing several things at once. The design branch covers how code uses flags: missing defaults, mishandled keys, secrets stored where they should not be, entangled flags and unstable user identities. The process branch covers how the team behaves around flags: never removing finished flags, leaving them without owners, rolling out too fast and giving too many people too much power. The operations branch applies mainly to self-hosted installations: missing backups, unwatched background workers and delayed upgrades.

The rest of the guide visits each leaf of this tree. For every mistake, we describe how it looks in real life, why it happens, what it costs and how to prevent it. At the end, we bring everything together in a worked example, a diagnostic path and a checklist.

This is the most famous flag mistake, and the one with the most dramatic stories. It deserves a careful look.

What it looks like

Someone intends to change a flag in development or staging but is actually looking at production. They toggle the flag, and real customers see an untested change straight away. Sometimes the opposite happens: a person switches a flag off in staging to fix a problem, believes production is fixed too and goes home, while customers continue to suffer.

Why it happens

Environments are deliberately similar: the same flags, the same layout, the same colours. The only difference may be a small name near the top of the page. When people work fast, switch between tabs or follow a link from a chat message, they can easily lose track of where they are. Remember that each environment has its own state for each flag, so the same toggle can be on in one place and off in another, and nothing about the toggle itself says which world it belongs to.

What it costs

The cost ranges from embarrassment to real outages. A wrong click in production can expose unfinished features, break checkout flows or switch off protective kill switches. Even when the mistake is spotted quickly, it takes time to understand what changed, and trust in the flag system takes a hit.

How to prevent it

A flag with a poor name works perfectly on the day it is created and becomes a puzzle a few months later.

What it looks like

The dashboard contains flags called test, new_feature, temp2 and fix. Their descriptions are empty. Nobody remembers who created them, what they control or whether they are still needed. Even worse, some names mean the opposite of what they appear to say, such as a flag called disable_search_v2 that is on when search version two should be off.

Why it happens

When creating a flag, the focus is on the feature, not on the person who will read the list next year. A quick name feels good enough. The description field is optional, so it is skipped. There is no agreed style, so each person invents their own.

What it costs

Unclear names slow everyone down. People hesitate to touch flags they do not understand, so stale ones stay forever. In emergencies, responders waste precious minutes working out which flag to change. Negative names breed double-negative confusion, such as “turn off the disable flag”, which is exactly the sort of sentence that causes errors under stress.

How to prevent it

The flag service will occasionally be slow or unreachable. What your application does at that moment is decided long before.

What it looks like

An application asks Flagsmith for a flag and assumes an answer will always arrive. When the network hiccups or the service is briefly unavailable, the application shows an error, hangs while waiting or behaves in an unplanned way. Sometimes the unplanned behaviour is that a half-finished feature appears for everyone, because “missing” was treated as “on”.

Why it happens

In development, the flag service is always available, so the failure path is never exercised. The code is written for the happy path and nobody asks what happens when the answer does not come. Defaults feel like extra work.

What it costs

The flag service becomes a hidden single point of failure. A short outage or a network problem in the flag path becomes an outage of the whole product. Worse, an unplanned default can expose features that were never meant to be seen.

How to prevent it

flowchart TD
    A["Application needs a flag answer"] --> B{"Fresh cached answer available"}
    B -- Yes --> C["Use cached answer"]
    B -- No --> D["Ask Flagsmith with a short timeout"]
    D --> E{"Answer received in time"}
    E -- Yes --> F["Use answer and refresh cache"]
    E -- No --> G{"Older cached answer available"}
    G -- Yes --> H["Use last known answer"]
    G -- No --> I["Use safe default defined in code"]

Reading the fallback chain

The ideal flag read has several layers of protection. First, check for a fresh cached answer, which avoids a network trip entirely. If there is none, ask Flagsmith, but only wait a short time. If an answer arrives, use it and refresh the cache. If it does not, fall back to the last answer that was known, because that is likely to be still correct. If there is no earlier answer at all, use a default defined in the code. Each layer reduces the chance that a flag outage becomes your outage.

• Define a default for every flag, and choose it deliberately. For new, unproven features the safe default is almost always off.
• Set short timeouts so a slow flag service never makes your pages slow.
• Let SDKs keep recent answers in memory or on the device.
• Test the failure path on purpose by blocking access to Flagsmith in a test environment.

Keys are the quiet connection between your application and the right set of flags. A wrong key produces confusing results that look like bugs.

What it looks like

An application reads flags from the wrong environment because it was given the wrong key. A staging build points to production flags, or a production build points to development flags. A developer sees the feature working on their machine and cannot understand why it is missing after release. Another team sees staging tests pass while production behaves differently, because staging and production were never really separate in the code.

Why it happens

Keys are long, similar-looking strings. They are copied by hand into configuration files and deployment settings, often under time pressure. Different environments need different keys, but configuration files are frequently copied between environments with the key left unchanged. When something works, nobody checks which environment it is actually reading.

What it costs

The cost is wasted debugging time and, in the worst case, test traffic influencing production flags or production flags being changed by test activity. It also destroys the main benefit of environments, which is a safe place to try things.

How to prevent it

• Keep each environment’s key in that environment’s configuration only, never in shared code.
• Name configuration entries clearly, so a key for production cannot be mistaken for one for staging.
• Show the active environment name somewhere in a test or admin screen, so you can see which world the application is reading.
• Add a simple startup check that logs which environment the application connected to, without logging the key itself.
• Review deployment configuration whenever a new environment is created.

Flagsmith provides different kinds of keys for different places. Using them in the wrong place can either expose too much or give you too little.

The two main kinds

A client-side key is designed for applications that run on users’ devices, such as web pages and mobile apps. It can only read flags, so it is safe to include in code that users can inspect. A server-side key is for trusted servers. It can do more, such as enabling local evaluation, where the server downloads the rules and decides flags itself. Because it is more powerful, it must be kept secret. There are also keys for the management interface, which can change configuration and must be guarded even more carefully. The exact names and capabilities can vary by version, so confirm them in the documentation.

What the mistake looks like

How to prevent it

• Use client-side keys in browsers and apps, and server-side keys only on servers.
• Store secret keys in a secrets manager or protected configuration, never in code repositories, chat messages or documents.
• Rotate any key that may have been exposed, and rotate keys periodically as a habit.
• Use separate keys for separate applications where your setup allows, so you can rotate one without disturbing the others.
• Search your repositories and build logs for accidental key leaks before they are found by someone else.

Flag values are convenient places to put configuration, and that convenience tempts people to store things that do not belong there.

What it looks like

Someone stores an access token, a password or a private address in a flag value because it is the easiest way to change it without redeploying. Another person puts a customer’s email address in a trait, or stores internal notes about a user in a value. The flag works perfectly, and the leak is invisible until someone looks at network traffic.

Why it is a problem

Flag values travel. They are sent to applications, and values read by browsers and mobile apps can be seen by anyone who inspects the traffic. They can appear in logs, in cached copies on devices, in audit entries and in webhook messages sent to other systems. A secret stored in a flag is effectively copied to every place the flag travels. Similarly, personal data sent as traits is stored in Flagsmith and may fall under privacy rules and customer promises.

How to prevent it

Use opaque identifiers, such as an internal user number, instead of names and emails. Send only the traits you genuinely need for targeting. Keep secrets in a secrets manager, and let the flag choose which behaviour to use, not carry the credentials.

The quietest mistake is also the most common. Flags are easy to add and surprisingly easy to forget.

What it looks like

A flag was created to roll out a feature. The rollout succeeded months ago. The flag is on for everyone and nothing interesting happens. But the code still contains both the old and the new behaviour, and the dashboard still lists the flag. Multiply this by dozens of releases and the code becomes a thicket of branches that nobody dares to touch.

Why it happens

After a successful release, attention moves to the next project. Cleaning up has no visible reward, and nobody owns it. The flag looks harmless, so it stays. Over time, nobody remembers whether it can be removed, which makes removing it frightening.

What it costs

Each stale flag leaves a dead branch in the code, extra tests, extra reading effort for new engineers and a small chance of an accident. The total, often called flag debt, slows every future change. In rare, dramatic cases an old flag is switched or reused by mistake and old code springs back to life.

flowchart LR
    A["Flag created for a release"] --> B["Release succeeds"]
    B --> C{"Cleanup scheduled"}
    C -- Yes --> D["Remove flag check and old path"]
    D --> E["Archive the flag"]
    C -- No --> F["Flag stays on for everyone"]
    F --> G["Code keeps dead branch"]
    G --> H["New engineers cannot tell what is safe"]
    H --> I["More flags added on top"]
    I --> J["Fear of touching anything"]

Reading the two paths

After a successful release, there is a fork. On one path, cleanup is scheduled, the flag check and the old code are removed and the flag is archived. Nothing is left to confuse anyone. On the other path, the flag stays on for everyone, the dead branch remains and each new engineer has to work out what is safe. As more flags are added on top, the whole system becomes something people are afraid to touch. The difference between the paths is a single decision made at the time of release.

How to prevent it

• Write the owner and the intended removal date in the description of every release flag.
• Include the cleanup task in the original piece of work, so the feature is not finished until the flag is gone.
• Review the flag list monthly, looking for flags that have been fully on or off for a long time.
• Remove the code first, deploy, confirm nothing still asks for the flag, and only then archive it.

It seems thrifty to reuse a name that already exists. In practice it is one of the most dangerous shortcuts in flag management.

What it looks like

A team needs a new flag and notices an old flag with a suitable name, perhaps one that was used for a previous feature and is now unused. They repurpose it for the new feature, change the description and carry on. Meanwhile, an old copy of the software somewhere still contains code that reacts to that name in the old way.

Why it is dangerous

A flag name is a promise between the dashboard and every piece of code that ever asked for it. Old versions of mobile apps, forgotten services, long-running jobs and archived scripts may still honour that promise in the old sense. When the meaning of a flag changes, those old pieces of code suddenly behave in unexpected ways. The industry has several cautionary stories in which old code, reactivated by a reused flag, caused serious damage within minutes.

How to prevent it

• Treat flag names as permanent and unique. Never reuse a name for a different purpose.
• Create a new flag for a new purpose, even if it feels wasteful.
• Keep a short record of retired names so they are not chosen again by accident.
• Search all repositories and services for the name before creating or retiring a flag.

One flag is easy to reason about. Ten flags that depend on each other are a puzzle with too many pieces.

What it looks like

A feature is protected by one flag, but inside it sits another flag, and inside that a third. A new payment form works only when flag A is on, flag B is on and flag C is off. Nobody can say what the product does when flag A is off and flag B is on. Or a single flag controls several unrelated behaviours, so that turning it off to fix one problem breaks something else.

Why it happens

Flags are cheap, so adding another flag to solve each new problem feels natural. Features grow over time, and each addition gets its own switch. Nobody steps back to ask how the switches relate.

What it costs

With a small number of flags, the number of possible combinations grows very quickly. Three flags make eight combinations. Ten flags make more than a thousand. No team can test them all, so some combinations run in production untested. The product becomes unpredictable, and incident responders cannot tell what turning a flag off will do.

How to prevent it

Targeting depends on recognising the same user each time. Careless identities make flags flicker or leak information.

What it looks like

A percentage rollout is set to ten percent, but the application generates a new random identifier on every visit. The same person sees the new feature on one visit and not on the next. Support receives confused reports of “the button keeps appearing and disappearing”. In another case, the application uses an email address as the identity, so personal data is stored in Flagsmith and shown in the dashboard.

Why it happens

Identities are easy to overlook. Developers need to provide something, so they provide whatever is at hand. Anonymous visitors have no user number, so a throwaway value is created each time. The consequences appear only when a rollout or an override depends on the identity staying the same.

How to prevent it

• Use a stable identifier that stays the same across visits, such as an internal user number.
• For anonymous visitors, generate a random identifier once and store it on the device, reusing it each time.
• Prefer opaque identifiers to names and emails, to protect privacy.
• Send only the traits you need, and keep their meaning consistent over time.
• Test a rollout by visiting several times as the same user, and confirm the answer stays the same.

Segments are powerful groups, and powerful things cause confusing results when their rules overlap.

A short reminder

A segment is a saved group of users defined by rules on their traits, such as users on a premium plan or users in a particular country. In a feature’s settings, a segment override says that users in that segment receive a different state or value from the default. A single user can belong to several segments at once, so more than one override may apply. When that happens, a priority order decides which one wins.

What the mistake looks like

A team creates a beta testers segment that turns a feature on, and a separate europe segment that turns the same feature off for legal reasons. A beta tester in Europe is in both segments. Which result do they get? If nobody thought about priority, the answer depends on an order that nobody chose on purpose. Other typical errors include rules written against a trait name that the application never sends, rules that match nobody because of a typing difference such as capital letters, and rules that match everybody because they are too broad.

How to prevent it

A flag makes it possible to release gently. Many teams throw that gift away by going from nothing to everything in one step.

What it looks like

The code is deployed, the flag is switched on for all users in one click, and the team moves on. Five minutes later the error rate climbs, but nobody is watching. By the time a customer complaint arrives, thousands of people have seen a broken experience. The flag can be turned off in seconds, yet the damage was done during the long minutes of silence.

Why it happens

Speed feels productive. The rollout plan is in someone’s head, not on paper. Monitoring is checked after the fact, not during the change. Teams trust that the feature is fine because tests passed in staging, forgetting that production has different data, scale and surprises.

What it costs

The benefit of a flag is limiting the blast radius of a mistake. A rollout straight to everyone makes the blast radius the whole user base. A slow, watched rollout shrinks it to a few percent, and gives you time to react.

How to prevent it

Decide the signals in advance

Before the rollout starts, write down what you will watch and what counts as bad. For example: error rate, response time, completion of the key user task and the number of support contacts. Agree thresholds in advance, so that you do not argue about whether a number is acceptable while it is climbing. Tell the team when the rollout starts and when each step changes.

A flag change is saved instantly, yet applications may notice it later. Not knowing this causes false alarms and false confidence.

What it looks like

A person switches a flag off during an incident and sees the toggle change in the dashboard. They assume the problem is solved. Minutes later, some servers are still showing the old behaviour, because their SDKs hold cached answers or refresh at intervals. Or the opposite: a person turns a flag on, refreshes their page, sees nothing and decides that the flag is broken, then flips it back and forth in frustration.

Why it happens

Different SDKs and settings behave differently. Some ask the service on every request. Some keep answers in memory for a while. Some servers use local evaluation, downloading rules and refreshing them periodically. Browsers and mobile apps may keep a copy on the device and refresh on a schedule. Most people only learn the behaviour of their own setup after being surprised by it.

How to prevent it

• Learn and write down the refresh behaviour of every application that reads your important flags.
• Choose refresh intervals deliberately, balancing freshness against load.
• For emergency kill switches, make sure the refresh interval is short enough to meet your needs, and test how long a change takes to spread.
• During incidents, verify the effect in the application itself, not just in the dashboard.
• Avoid flipping a flag repeatedly while waiting. Each flip can leave different servers in different states.

Every flag question has a cost. Applications that ask too often waste time, money and the patience of the flag service.

What it looks like

A server asks Flagsmith for the same flag many times during a single request. A loop checks a flag on every item in a long list. A mobile app contacts the service every time a screen is shown. A browser page asks for the flags again at each step of a flow. The flag service works hard, response times creep up, and costs rise on hosted plans that charge by request volume.

Why it happens

Flag checks look cheap in code: they read like ordinary function calls. When the SDK hides the network trip, developers forget that each call might travel across the internet. The habit of “just ask again when I need it” scales badly as traffic grows.

How to prevent it

A flag dashboard is a lever on your live product. Who may pull it, and who can see it being pulled, are design decisions.

What it looks like

Everyone in the company has administrator rights because it was easier at the start. A single shared login is used by the whole team. Former contractors still have access. Nobody reads the audit log. When something changes unexpectedly, no one can say who did it or why.

Why it happens

Early on, the team is small and trust is high, so careful access feels like bureaucracy. As the team grows, the original arrangement quietly becomes the rule. Nobody owns the task of reviewing access.

What it costs

Wide permissions increase the chance of accidental changes and widen the blast radius of a stolen account. Shared logins destroy accountability, since the audit log shows the same name for everyone. Without visibility, investigating an incident takes far longer.

How to prevent it

Every flag doubles the paths through your code. Teams that test only the happy path meet the other path in production.

What it looks like

The new code is tested thoroughly with the flag on. Nobody tests with the flag off, because that is “the old code which already works”. After a change elsewhere, the off path quietly breaks. When the flag is switched off to roll back a problem, the rollback itself fails. In another variation, tests depend on the live flag service, so they pass one day and fail the next because someone changed a flag in the dashboard.

Why it happens

Testing effort follows attention, and attention goes to the new feature. The off path feels like a given. Making tests independent of the live service takes a little setup that is easy to skip.

How to prevent it

Running Flagsmith yourself gives control and also adds chores. Most self-hosting troubles come from skipping the chores.

No tested backups

The database holds every flag, segment, user and audit entry. A team sets up automated backups and feels safe, but never restores one. When a disk fails or a command removes the wrong data, the backup turns out to be incomplete, unreadable or too old. A backup that has never been restored is only a hope. Schedule backups, store them away from the main system, encrypt them and rehearse the restore regularly, writing down how long it takes.

Database in a throwaway container with no protection

For convenience, the database runs in a container with its data on temporary storage, or on a local folder with no copies. A routine cleanup removes the storage, and everything vanishes. For production, prefer a managed database or a carefully operated one with automated backups and a standby, and keep the data on storage that survives container replacement.

Using the latest tag in production

The container configuration says to pull the newest image. A restart on an ordinary day brings in a new version with changes nobody tested, perhaps including database changes that cannot easily be undone. Pin an exact version, test upgrades in staging and change the version only on purpose.

Forgetting the background worker

Webhooks, audit processing and analytics rely on background work. In larger setups this runs in a separate task processor. If that worker stops, the dashboard still works and flags still evaluate, so nobody notices. Webhooks silently stop and records fall behind. Include the task processor in monitoring and alerts, and make sure it has permission to reach the outside addresses it needs.

Exposing the database or the application directly

For convenience, the database port is published to the internet, or the application is reachable without a reverse proxy and HTTPS. Automated scanners find open ports within hours. Keep the database on a private network, expose only a properly configured reverse proxy, and test from outside to confirm.

Skipping upgrades

Because nothing seems broken, upgrades are postponed month after month. Security fixes are missed, and the eventual jump to a modern version becomes large and risky. Upgrade in small, regular steps: read the release notes, back up, test in staging, migrate in a controlled step, replace containers gradually and keep the backup as the rollback tool.

Webhooks tell other systems when flags change. They are helpful, and they have their own classic pitfalls.

No signature check

A receiver accepts any message sent to its address. A stranger who discovers the address can forge messages claiming that flags changed, triggering cache wipes, deployments or alerts. Configure a secret, verify the signature over the raw message body, use a constant-time comparison and reject anything that does not match.

Doing slow work before replying

The receiver tries to complete all its work, including calls to other services, before answering. The sender times out, retries, and the receiver now handles the same message twice. Verify, store the message safely, reply quickly with a success code and do the real work in the background.

Assuming exactly once, in order

Deliveries can arrive more than once, late or out of order. Receivers that add one to a counter, or overwrite state with whatever arrived last, drift into error. Make actions safe to repeat, compare timestamps inside messages and periodically reconcile with the real state from the Flagsmith interface.

Staying silent when it breaks

When a webhook pipeline fails, nothing visibly happens, which feels like peace. A cache stays stale or an audit archive misses a week. Monitor message volume, errors and backlog, alert when expected messages stop arriving, and consider a scheduled harmless test change as a heartbeat.

Wiring a message straight to a dangerous action

A webhook triggers a deployment or a deletion directly. If a message is forged, duplicated or delayed, a small mistake becomes an outage. Put a safety check between the message and any destructive action, and re-read the real state before acting.

Ending a flag’s life, or moving a whole setup elsewhere, are moments when small oversights have large effects.

Archiving a flag that is still asked for

A person archives a flag that looks finished, but a running application still asks for it. The application now receives no answer for that flag and falls back to its default. If the default is wrong, behaviour changes suddenly for some users. Mobile apps are the classic case, because old versions stay on phones for months. Remove the code, deploy, confirm via logs or monitoring that nothing asks for the flag, and only then archive.

Deleting in a hurry during cleanup

A cleanup day turns into a mass deletion. Flags that look stale are removed without checking owners or code. One of them guarded a rarely used but important path. Clean up in small batches, with owners consulted and the audit log checked.

Migrating without a plan for keys and identities

When moving between the hosted service and a self-hosted installation, or between organisations, teams often assume everything moves automatically. In reality, environment keys change, so every application needs updating. Identity data and history may not travel the way configuration does. Read what your chosen method moves, rehearse the migration in a test environment and move applications in stages with a rollback plan.

Forgetting to keep an export

Nobody keeps a human-readable copy of the flag configuration outside the database. After a serious loss, rebuilding by memory takes days. Take regular exports through Flagsmith’s own interfaces and store them safely.

flowchart TD
    A["Decide to retire a flag"] --> B["Search all code and active app versions"]
    B --> C{"Anything still asks for it"}
    C -- Yes --> D["Wait or update those apps first"]
    D --> B
    C -- No --> E["Remove flag checks and old code path"]
    E --> F["Deploy and watch monitoring"]
    F --> G{"Any requests for the flag in logs"}
    G -- Yes --> D
    G -- No --> H["Archive the flag in Flagsmith"]
    H --> I["Record the retired name"]

Reading the retirement path

The path begins with a search across all code and all active versions of every application. If anything still asks for the flag, you wait or update those applications first. Only when nothing asks do you remove the checks and the old path, deploy, and watch the monitoring. If logs still show requests for the flag, you go back. Only after a quiet period do you archive the flag, and you record its name so that nobody reuses it.

Many flag problems are not technical. They come from how teams talk to each other, or fail to.

No owner

Flags are created by individuals and used by teams, yet nobody owns them. When a flag misbehaves, each team assumes another team will handle it. Give every flag a named owner, and record the owner in the description.

No shared language

Teams use different names for the same flag, different words for environments and different expectations for what on means. Agree a vocabulary, a naming style and a short guide, and use the exact flag name in tickets, release notes and chat.

Changes without announcements

Someone changes a production flag and tells no one. A colleague, chasing a bug, spends hours before discovering that a flag changed an hour earlier. Post production changes to a shared channel with the flag name, environment, person and reason. The audit log records the facts, but a message in the channel tells people at the moment they need it.

No rehearsal of emergencies

Kill switches exist, yet the team has never practised using them. During a real incident, people hesitate over which flag to change, whether they have permission and how long it takes to take effect. Rehearse kill switches in a calm moment, write short instructions and check the timing.

No regular review

Nobody schedules time to tidy flags, review access or check settings. Problems accumulate silently. A short monthly review of flags, users, keys and alerts costs less than one bad incident.

Serious incidents are rarely caused by one error. They happen when several small weaknesses line up. Let us watch it happen in slow motion.

sequenceDiagram
    participant E as Engineer
    participant D as Dashboard
    participant P as Production Servers
    participant C as Customers
    participant S as Support
    E->>D: Open flag from a chat link
    Note over E,D: Link opens Production, not Staging
    E->>D: Toggle checkout_new_payment_form OFF
    D-->>E: Change saved, no approval needed
    D->>P: New state available to SDKs
    P->>P: Some servers refresh now, others after cache expires
    P-->>C: Customers see a mix of old and new checkout
    Note over P,C: Old path was never tested after recent change
    C->>S: Reports of failed payments
    S->>E: Asks what changed
    E->>D: Checks audit log, finds own change
    E->>D: Toggle back ON
    P-->>C: Behaviour settles after caches refresh

Reading the chain

The story starts with a link in a chat message that opens production rather than staging. The engineer toggles a flag, intending to test the old checkout path. Nothing stops the change, because production changes need no approval. The new state spreads to servers at different times, since each refreshes on its own schedule, so customers see a confusing mixture. The old path, which has not been tested since a recent change, turns out to be broken, so payments fail. Support asks what changed, and the engineer finds the answer in the audit log, toggles the flag back, and waits for the caches to settle.

Count the weaknesses: a look-alike environment, a missing approval, an untested off path, a mixed refresh timing, no announcement and slow discovery. Fix any one of them and the incident is smaller or disappears. Fix several and it never happens.

Slices you can add

When a flag misbehaves, the first minutes matter. A fixed order of questions beats guesswork.

flowchart TD
    A["Something looks wrong with a flag"] --> B["Check the audit log for recent changes"]
    B --> C{"A relevant change found"}
    C -- Yes --> D["Confirm environment and who changed it"]
    D --> E["Decide: revert the change"]
    C -- No --> F{"Is the app reading the right environment key"}
    F -- No --> G["Fix the key and redeploy"]
    F -- Yes --> H{"Does the flag name match exactly"}
    H -- No --> I["Correct the spelling"]
    H -- Yes --> J{"Do identity or segment overrides apply"}
    J -- Yes --> K["Review override and priority order"]
    J -- No --> L{"Could a cache be hiding the change"}
    L -- Yes --> M["Wait for refresh and verify again"]
    L -- No --> N{"Can the app reach Flagsmith"}
    N -- No --> O["Fix network, address or certificate; confirm defaults"]
    N -- Yes --> P["Check service health and escalate"]

Reading the path

Always begin with the audit log, because the most likely cause of a surprise is a recent change. If a relevant change exists, confirm the environment and the person, and decide whether to revert. If not, check that the application reads the right environment key, then that the flag name matches exactly. Next consider overrides: a rule for the identity or a segment may explain why one user sees something different from another. Then think about caches, which may simply be showing an older answer. Then check connectivity: if the application cannot reach Flagsmith, it is using defaults. Only after these steps should you suspect the service itself.

Use this checklist at the start of a project, before a big release and during your regular reviews.

At the dashboard

• I have read the environment name before clicking.
• The flag has a clear name, a useful description, an owner and an end date.
• I am changing one thing at a time, and I have told the team about production changes.

In the code

• Every flag read has a safe default and goes through one wrapper.
• Keys are of the right type, stored safely and tied to the right environment.
• No secrets or unnecessary personal data appear in values or traits.
• Identities are stable and opaque.
• Tests cover flag off, flag on, service unavailable and invalid values.

In the rollout

• The rollout plan lists steps, signals and thresholds.
• Someone is watching, and someone knows how to turn the flag off.
• The refresh timing of every application has been measured.

In the team

• Production changes are limited, approved where possible and announced.
• The audit log is the first stop in incidents.
• Kill switches have been rehearsed.
• Flags are reviewed monthly and retired promptly.

In operations, if self-hosted

• Images are pinned and mirrored, and upgrades are regular and rehearsed.
• The database is protected, backed up and restored in drills.
• The task processor is monitored, and alerts cover silence as well as errors.
• Only the reverse proxy is public.

Flag mistakes are not unique to Flagsmith, and not unique to small teams. Large, careful organisations have met the same problems.

Percentage rollouts feel mathematical and therefore safe. In practice they hide several traps that catch careful teams.

Mistake: reading too much into a tiny sample

A team enables a feature for one percent of users, sees no complaints after an hour, and declares success. But one percent of a small audience may be a handful of people, and an hour may not include the busiest moments, the unusual devices or the rare but costly actions. Silence is not evidence when almost nobody was looking. Decide in advance how many users and how much time you need before the next step, and write the numbers in the rollout plan.

Mistake: forgetting that the split depends on the identity

Flagsmith places each identity into a bucket in a stable way, so the same person receives the same answer each time. That is a good thing, but it means a percentage only works when identities are stable. If your application sends a fresh random identifier on every visit, the same person is shuffled in and out of the feature, and the experience flickers. If you send no identity at all, the percentage rule may not behave as you expect. Always check how your application identifies visitors before relying on a split.

Mistake: moving the percentage down and up carelessly

Lowering a rollout from fifty percent to ten percent removes the feature from most people who had it. Raising it again later may bring back some of those people, but you should not assume it brings back exactly the same ones. For users who had already stored data created by the new feature, a sudden removal can cause confusing screens. When you reduce a rollout, think about what those users have already done with the feature, and whether the old path can handle their data.

Mistake: running two experiments that overlap

If two flags both change the checkout page, a user may land in both groups at once. Any change in sales could belong to either experiment, or to the combination. Teams then argue about results that cannot be separated. Keep a simple calendar of running experiments, avoid overlapping changes on the same screen and name the experiment owner on each flag.

Mistake: judging by the wrong measure

A new button may be clicked more often, yet lead to fewer completed purchases. Choose the measure that reflects the real goal before the experiment starts, not after you see which number looks best. Choosing the measure afterwards is like drawing the target around the arrow once it has landed.

Mobile applications and growing usage bring their own surprises. Both are easy to overlook until they hurt.

Mistake: forgetting that old app versions live on

A website updates for everyone the moment you deploy. A mobile app does not. Thousands of people keep running old versions for months. If you remove a flag from the dashboard or change what its values mean, those old versions still ask for it. They may receive nothing, fall back to their defaults, or misread a new value. Before changing or retiring a flag used by mobile apps, find out which app versions still exist and what they expect.

Mistake: depending on a fresh network connection

Phones go into tunnels, lifts and aeroplane mode. An app that needs a fresh answer before drawing its first screen will feel broken on a weak connection. Let the app start with stored answers from its last successful visit, or with sensible defaults, and update quietly in the background. Decide deliberately whether a change should take effect at once while the user is looking, or at the next launch, since changing a screen under someone’s thumb can be jarring.

Mistake: asking too often

Some teams, wanting quick updates, set very frequent refreshes on every device. Multiplied by a large user base, that produces a flood of requests, draining batteries, using mobile data and raising the bill or the load on your own servers. Choose a refresh rhythm that matches how quickly you genuinely need changes to spread. Most flags do not need second-by-second freshness; the few that do, such as emergency switches, can be treated specially.

Mistake: ignoring plan limits until they bite

Hosted plans usually include limits, such as numbers of requests, projects, team members or features. A product that suddenly becomes popular can pass a limit unexpectedly, and the consequences depend on the plan. Learn your limits, watch your usage and decide who is told when you approach them. For self-hosted setups, the equivalent surprise is capacity: the database and servers must grow as traffic grows.

Mistake: treating cost as someone else’s problem

Every extra environment, every duplicated project and every over-eager refresh has a price in money, attention or both. A short quarterly review that asks which projects are unused, which environments are idle and which applications make the most requests often finds easy savings.

Every important word used in this guide, in plain language, for quick lookup.

Short answers to the questions people ask most often about avoiding flag mistakes.

Everything in this guide comes down to a handful of ideas you can carry into your next release.

Feature flags make software safer, but only when the habits around them are sound. The most common mistakes are not exotic. They are acting in the wrong environment, leaving out defaults, mishandling keys, storing secrets in values, never removing flags, reusing names, rolling out too fast and ignoring operations. Each has a simple, cheap remedy, and the remedies stack: every habit adds another slice of protection, and incidents need many holes to line up at once.