What makes a feature flag stale, and why do they never get removed?
A flag is stale when evidence shows it no longer makes a decision. Age alone does not make it stale. Three conditions together make a strong case:
- It returns the same value everywhere. Every environment and every tenant has evaluated to one value for a defined window, such as a full release cycle plus a buffer.
- Nobody has changed its config. No targeting rules, percentages, or overrides have been edited in that window.
- Its purpose is formally closed. The rollout reached 100% and was signed off, or the experiment has a recorded result.
A flag that meets all three is flag debt: a conditional that still costs you something but no longer buys you anything. The cost is concrete. Every dead branch is another path that tests should cover, another case reviewers must think through, and another "what if this is off?" question for anyone changing nearby code. In a monolith, that overhead lands on every team that touches the module, not just the team that added the flag.
Flags linger in monoliths for predictable reasons. Nobody can prove a flag is dead, because callers are spread across packages and config lives somewhere else. The original owner has moved teams. And being wrong feels worse than doing nothing: a bad removal causes an incident, while a leftover flag only causes friction nobody gets blamed for.
This guide is for backend and platform engineers who work in shared codebases and want to remove stale feature flags as routine code hygiene. The goal is not a heroic cleanup sprint. It is to make deadness provable, so that toggle cleanup becomes a low-risk, repeatable change.
When should you remove a stale flag, and when should you wait?
Remove a flag when its job is finished and you can prove it. These are the usual triggers:
- A release toggle has been fully on in every environment for at least one release cycle. At that point the flag can no longer roll anything back that a deploy revert couldn't, and the old branch is only getting more out of date.
- An experiment has a recorded decision. Once the result is written down, the losing variant is just code nobody will run again.
- You are about to refactor or migrate a module. Remove its dead flags first, in separate changes. Refactoring around a branch that never runs doubles the work and hides the real diff.
- The expiry date in the flag's metadata has passed, or the weekly report lists it as serving a single value everywhere.
- A flag keeps coming up in reviews or incident debugging as "does this path still matter?" That question is the cost showing up, and it is worth paying down.
Wait, or don't remove at all, in these cases:
- The flag is a kill switch or an entitlement. These are not temporary by design (see the classification below).
- The flag gates a data shape and the backfill is not complete and verified.
- The observation window has not yet covered rare paths, such as month-end or year-end jobs, disaster-recovery procedures, or tenants with unusual configuration.
- The codebase is in a release freeze or an active incident. Cleanup is low-risk, but it is never urgent, so it should not compete with stabilisation work.
Which flags should you remove, and which should you keep?
Before deleting anything, classify each flag by why it exists. Only two of the four common classes are meant to be temporary, and confusing them is how cleanup causes outages.
| Class | Purpose | Expected lifetime | Retirement rule |
|---|---|---|---|
| Release toggle | Hide incomplete or unproven code on trunk | Days to weeks after full rollout | Remove once fully on in every environment for at least one release cycle |
| Experiment | Compare variants and measure outcomes | Length of the test plus analysis | Remove when the decision is recorded; delete the losing branch with it |
| Ops / kill switch | Shed load or disable a risky dependency fast | Indefinite | Keep; periodically confirm it still works and has an owner |
| Permission / entitlement | Gate behaviour by plan, tenant or role | Life of the feature | Not stale by definition; move to an entitlement system if it outgrows flags |
The common mistake is treating "unchanged for a year" as proof of deadness. A kill switch that has never been flipped is doing its job. Remove it and you lose the only fast lever during the next incident. An entitlement flag that is on for every tenant except one looks constant in dashboards, but deleting it changes behaviour for that tenant.
Flags that gate data shape
Flags controlling dual writes, reads from a new column, or a migration path are a special case. Removing one commits the code to a single data shape. If old-format rows still exist, the remaining path will hit data it cannot handle. Remove these only after the backfill is complete, verified against the source, and dual writes have stopped. The schema cleanup comes last.
How does evidence-driven flag removal work?
The process is a pipeline. Each stage narrows the set of candidates and keeps the next step reversible by the cheapest available means.
- Classify. Tag every flag as release, experiment, ops or entitlement. Only release and experiment flags move forward. Data-shape flags move forward only once their migration is finished.
- Collect evidence from three sources. Join the flag store, the code references and runtime evaluation counts on flag name. A flag becomes a candidate only when all three agree that it serves one value, or that nothing reads it.
- Pin. Collapse the flag's config to the winning value with no targeting or splits. This turns "probably constant" into "definitely constant". At this stage, rollback is still a config change.
- Soak. Leave it pinned long enough to cover the periodic jobs your observation window was designed for.
- Remove the code. Delete the check, the losing branch, its helpers and its tests in one pull request per flag. Do this by hand, or with a codemod where the call sites are simple.
- Verify the deploy. Confirm from the evaluation counts that no running build still reads the flag.
- Delete the definition from the store.
- Prevent recurrence. New flags carry an owner, a type and an expiry date, and a scheduled report feeds the next round of candidates back into step 2.
The safety comes from the ordering. Evidence is gathered before anything changes. Config changes come before code changes. Code changes come before the definition is deleted. At every point, the cheapest rollback is still available. The sections below cover each stage in detail.
How do you prove a flag is dead?
A flag is dead when three independent sources agree: the flag store or config file, the code, and runtime evaluation data. Each source alone misleads. The store lists flags nobody reads, grep misses names built from strings like "checkout_" + region, and runtime data only covers traffic that actually happened.
Reconcile them as a three-way join on flag name:
| In store | In code | Evaluated | Finding |
|---|---|---|---|
| yes | yes | yes | Live; inspect results |
| yes | no | no | Orphaned config; delete entry |
| no | yes | any | Unregistered reference; falls back to default silently |
| yes | yes | no | Unproven; check rare paths |
Treat the second and third rows as defects, not noise. An unregistered reference means behavior depends on a hardcoded default that nobody reviews.
For runtime data, route every evaluation through a single accessor that increments an in-memory counter keyed by flag, call site, and result. Flush the aggregates periodically. Per-evaluation logging on a hot path costs too much, while aggregated counts are cheap and still separate the cases you care about: always one value, never evaluated, or still varying. Call site matters because a flag can be constant in the web tier and still vary in a worker.
Keep the observation window long enough to cover batch jobs, cron tasks, admin tools, quarter-end or year-end processing, disaster-recovery paths, and tenant-specific code. A two-week window will report a year-end flag as unused.
import atexit
import sys
import threading
from collections import Counter
class FlagAccessor:
"""The only code path allowed to read flags. Records aggregated counts, not per-call logs."""
def __init__(self, store, emit):
self._store = store # dict-like: supports `in` and .get(name, default)
self._emit = emit # callable that ships one batch of rows to your metrics sink
self._counts = Counter()
self._lock = threading.Lock()
# Short-lived cron and batch processes can exit before any periodic flush runs.
# Flushing at exit keeps rare paths in the data.
atexit.register(self.flush)
def is_enabled(self, name, default=False):
registered = name in self._store # False means an unregistered reference that silently uses the default
value = bool(self._store.get(name, default))
# Record the caller's file:line, so a flag that is constant in the web tier
# but varies in a worker shows up as two rows. sys._getframe is CPython-specific,
# but it is far cheaper than inspect.stack() on a hot path.
caller = sys._getframe(1)
site = f"{caller.f_code.co_filename}:{caller.f_lineno}"
with self._lock:
self._counts[(name, site, registered, value)] += 1
return value
def flush(self):
# Swap the counter under the lock, then emit outside it so a slow sink never blocks flag reads.
with self._lock:
batch, self._counts = self._counts, Counter()
if batch:
self._emit([
{"flag": f, "site": s, "registered": reg, "result": r, "count": c}
for (f, s, reg, r), c in batch.items()
])
A single flag-access wrapper that keeps in-memory counts keyed by flag, call site, registration status and result, then flushes them periodically and on process exit so short-lived batch and cron jobs are still counted.
How do you remove a stale feature flag without causing an incident?
Removal is a sequence, not a single edit, and the order is what keeps it safe.
- Pin the flag to its winning value in config and let it soak. Remove all targeting rules, percentage splits and per-tenant overrides so every evaluation returns the same value. If anything breaks, you can still revert with a config change instead of a deploy.
- Delete the losing branch and the flag check. The winning branch becomes unconditional code.
- Simplify the surrounding code. Delete helpers that only the losing path called, tests that exercise the removed path, and any config keys or constants that existed to support it. Dead helpers left behind become the next archaeology project.
- Deploy, and confirm that no running version still evaluates the flag.
- Only then delete the flag definition from the store.
Step 5 comes last because code that evaluates a flag missing from the store does not fail loudly. The SDK or your wrapper falls back to a default, and that default may be the opposite of the winning value. A lagging replica, a long-running worker or a rollback to an older build would silently flip back to the losing behavior. Check what your own SDK or wrapper returns for an unknown key. Until the check is gone, make the default explicit at the call site and set it to the winning value.
Keep it to one flag per pull request so a revert is clean. The team that owns the code path should own the change, and the losing branch's tests should be deleted in the same diff as its code. The example below shows a pinned flag before and after removal.
// BEFORE: flag pinned to true in the store (no targeting, no splits).
// The explicit default matches the winning value, so a missing
// definition cannot flip this back to the legacy path.
export async function priceCart(cart: Cart, ctx: RequestContext): Promise<Price> {
const useNewPricing = flags.isEnabled("checkout.new-pricing-engine", ctx, {
defaultValue: true, // winning value, stated at the call site
});
if (useNewPricing) {
return pricingEngine.quote(cart, ctx.currency);
}
// Losing branch: only caller of legacyTaxAdjust and legacyRound.
const subtotal = legacyTaxAdjust(cart.items, ctx.region);
return legacyRound(subtotal, ctx.currency);
}
// AFTER: same PR also deletes legacyTaxAdjust, legacyRound and
// the tests that covered the legacy path. The flag definition stays
// in the store until no deployed build still evaluates it.
export async function priceCart(cart: Cart, ctx: RequestContext): Promise<Price> {
return pricingEngine.quote(cart, ctx.currency);
}
A pricing function before and after removing a flag pinned to its winning value: the explicit default guards the soak period, and the removal deletes the legacy branch and its helpers in one change.
Can toggle cleanup be automated with codemods?
Partly, and the answer depends on how flags are read. If every check goes through a single wrapper, such as flags.isEnabled("new_checkout"), then finding references is a literal-string search, and a tool can match the call precisely instead of guessing. Codebases where some code reads the flag client directly and other code reads environment variables give you no complete list to work from.
With a single entry point, an AST-based codemod can do the mechanical work. It parses each file, finds calls whose flag name is a string literal, replaces the call with the winning value, simplifies the conditional, and deletes the dead branch. Because it operates on the syntax tree rather than on text, it does not damage formatting or match a flag name that appears inside a comment.
For an illustrative example, take if (flags.isEnabled("new_checkout")) { newFlow() } else { legacyFlow() }. This is safe to rewrite to newFlow(). By contrast, if (flags.isEnabled(region + "_pricing") && !user.isBeta) needs a human. The name is built at runtime, and the compound condition does not simplify to a single branch.
Automation also breaks down in these cases:
- nested flags, where removing the outer flag changes which inner path runs
- template files and YAML or JSON config, which the parser never sees
- flags that gate migrations or schema changes, where the code path and the data state must agree
Tooling does not remove the need for review. It changes what review involves. Investigating each flag by hand takes bespoke effort every time. A codemod produces uniform diffs that a reviewer can check in minutes, which leaves engineering time for the cases the tool flags as unsafe.
// jscodeshift transform: retire one flag whose rollout finished at 100%.
const FLAG = 'new_checkout';
const WINNER = true; // value the flag resolved to in production
module.exports = function transformer(file, api) {
const j = api.jscodeshift;
const root = j(file.source);
// Only the single wrapper is recognised: flags.isEnabled(<one argument>)
const isFlagCall = (n) =>
n.type === 'CallExpression' &&
n.callee.type === 'MemberExpression' &&
n.callee.object.name === 'flags' &&
n.callee.property.name === 'isEnabled' &&
n.arguments.length === 1;
const nameOf = (n) => {
const a = n.arguments[0];
return (a.type === 'StringLiteral' || a.type === 'Literal') && typeof a.value === 'string' ? a.value : null;
};
// Safe case: the whole if-test is exactly flags.isEnabled('new_checkout').
root.find(j.IfStatement)
.filter((p) => isFlagCall(p.node.test) && nameOf(p.node.test) === FLAG)
.forEach((p) => {
const branch = WINNER ? p.node.consequent : p.node.alternate;
if (!branch) return p.prune(); // no winning branch: drop the statement
const blockScoped = branch.type === 'BlockStatement' &&
branch.body.some((s) => s.type === 'VariableDeclaration' && s.kind !== 'var');
// Inline the block body unless let/const would leak into the outer scope.
if (branch.type === 'BlockStatement' && !blockScoped) p.replace(...branch.body);
else p.replace(branch);
});
// Everything left over goes to a human: built names, compound conditions, ternaries.
root.find(j.CallExpression).filter((p) => isFlagCall(p.node)).forEach((p) => {
const name = nameOf(p.node);
if (name === null || name === FLAG) {
console.warn(`${file.path}:${p.node.loc.start.line} flag check needs manual review`);
}
});
return root.toSource();
};
Illustrative jscodeshift codemod that inlines if (flags.isEnabled("new_checkout")) to its winning branch and lists every remaining check that has a dynamic name or sits in a compound expression for a reviewer, without touching it.
How do you stop flag debt from accumulating?
Cleanup only stays cheap when it is continuous, so the controls belong at flag creation, not at an annual purge.
Require metadata when a flag is created
Every flag definition should state who owns it, what class it is, and when it should be gone. A minimal block has these fields:
owner: a team, not a person, so the flag survives reorgs and departures.type: one ofrelease,experiment,ops(kill switch) orentitlement.expires: a date, required forreleaseandexperiment.
Enforce this in code review or with a CI check that rejects flag definitions missing any field. At creation, the author knows exactly why the flag exists. Six months later, nobody does.
Report and enforce expiry
Run a weekly job that lists removal candidates: expired flags, and flags that have served a single variant everywhere since the last report. Add a CI check against the same data.
You have to choose how strict that check is:
- A hard failure stops growth. It also teaches engineers to push the expiry date forward to unblock a merge.
- A warning is tolerated, but people learn to ignore it.
A workable middle ground is to warn on expiry and fail only after a grace period. Also require a written reason with any date extension, so each bump leaves a record.
Exempt kill switches and entitlements by type, not by giving them a far-future date. Fake dates erode trust in every other expiry.
Finally, publish the stale-flag count per team where people will see it. A visible number gets attention that a backlog ticket does not.
flags:
- key: checkout-new-tax-engine
owner: team-payments # a team, not a person; survives reorgs
type: release # release | experiment | ops | entitlement
expires: 2027-01-15 # required for release and experiment
purpose: Gradual rollout of the rewritten tax calculation path.
- key: checkout-one-click-upsell
owner: team-growth
type: experiment
expires: 2026-12-01
purpose: A/B test of the upsell prompt on the confirmation page.
# Each date bump must append an entry here, so extensions leave a record.
extensions:
- from: 2026-11-01
to: 2026-12-01
reason: Test underpowered; holiday traffic needed for significance.
- key: checkout-disable-fraud-scoring
owner: team-risk
type: ops # kill switch: no expires, exempt by class
purpose: Bypass the fraud scoring call if the scoring service degrades.
- key: checkout-invoice-billing
owner: team-billing
type: entitlement # tied to customer plans, exempt by class
purpose: Enables invoice billing for accounts on the enterprise plan.
An example flag-definition file in which every flag declares a team owner and a type, release and experiment flags carry an expiry date with a recorded reason for each extension, and kill switches and entitlements are exempt by type rather than by a far-future date.
How can removing stale flags save engineering time?
Most of the savings come from not paying small, recurring costs, so they are spread across many people rather than appearing as one line item.
- Fewer paths to test and reason about. Each independent boolean flag in a code path doubles the number of possible combinations. Three flags in one function give eight combinations, and four give sixteen. Removing a dead flag halves the space that tests, reviewers and debuggers have to consider in that code.
- Shorter reviews. Reviewers stop asking whether a change also works with the flag off. Diffs that touch flagged code get smaller, because nobody has to update both branches.
- Faster incident debugging. During an incident, every flag on the failing path is a hypothesis someone has to rule out. Dead flags add hypotheses without adding information.
- Less test and CI work. Tests for the losing branch go away with it. So does the effort of keeping those tests passing through unrelated refactors.
- Cheaper onboarding and refactoring. New engineers read the code that actually runs. Refactors no longer have to preserve behaviour on a path nobody uses.
- Investigation becomes a pipeline instead of an interview. Evidence from the three-way join replaces chasing the original owner for context. Codemods turn a bespoke investigation into a uniform diff that a reviewer can approve quickly. Engineering attention goes to the flags the tooling marks as unsafe.
Illustrative estimate, assumed inputs: a module that 10 engineers change regularly, each assumed to lose 15 minutes a week to dead-branch overhead, such as reading it, updating its tests or asking whether it still matters. That comes to 2.5 engineer-hours a week, or about 130 hours a year, for that one module. If removing its stale flags is assumed to take 2 engineer-hours each for 10 flags, the cleanup costs 20 hours. Replace these assumptions with your own figures before using them to justify the work.
What are the trade-offs and alternatives to continuous flag removal?
Continuous removal is one model among several, and each one handles unowned flags differently.
| Approach | Speed | Business context | How it stalls when ownership is unclear |
|---|---|---|---|
| Periodic cleanup sprints | Bursty; debt regrows between sprints | Low; engineers guess at flags they didn't write | Unowned flags are skipped "until next sprint" |
| Central platform team | Steady, but one queue for the whole codebase | Low; must ask owners each time | Only obviously safe flags go; the rest wait on replies |
| Delegation to owning teams | Varies with each team's backlog | High | Orphaned flags have nobody to delegate to |
| Continuous evidence-driven removal | Fast where telemetry is clear | Medium; evidence substitutes for memory | Someone still has to approve the merge |
Remaining trade-offs
Full evaluation telemetry gives certainty but adds cost and latency on hot paths. Sampling is cheaper but can miss a branch that runs once a month. Longer observation windows catch quarterly jobs, but they slow cleanup.
Pinning a flag before deleting it keeps rollback to a config change. The cost is that the flag lives longer. Deleting immediately is faster, but rollback then means revert and redeploy. Once you delete the losing path, it only exists in version control history. If you need it again, you have to rebuild it from there, against code that has since moved on.
Development cost
Illustrative estimate, assumed inputs: 400 stale flags at 2 engineer-hours each, covering the change, review and deploy. That is 800 hours, or about five engineer-months at 160 hours a month. Tooling that halves the per-flag time saves 400 hours, but only if building it costs less than that.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to remove stale feature flags, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.