Guide

Feature flag cleanup: removing stale flags safely

Every release flag is meant to be temporary, and most outlive their purpose. How to find the ones that are safe to remove, remove them without surprises, and keep the backlog from growing back.

A stale feature flag is a temporary flag whose decision has already been made: it serves one value to everyone, everywhere, and hasn't changed in a while. Removing it means deleting the flag check and the code path that lost, then retiring the flag.

Why stale flags are technical debt

  • Dead code that still looks alive. The losing path stays in the codebase, gets refactored, and confuses everyone who reads it.
  • Untested paths. Nobody tests the "off" path of a flag that has been on for a year, but it is still one click away in production.
  • Accidental reactivation. A flag that still exists can be flipped by mistake, or reused under the same name for something new.
  • Noise. The more flags in the list, the harder it is to find the ones that matter during an incident.

Which flags to clean up, and which never to touch

Cleanup applies to temporary flags. Permanent flags only look stale:

KindTemporary?Clean up when
ReleaseYesAt 100% (or 0%) everywhere and stable, usually within weeks
ExperimentYesThe test is analysed and the winner is serving to everyone
Ops (kill switch)NoThe dependency or code path it protects is removed
Permission (feature gate)NoThe gated feature or plan no longer exists

Finding stale flags

A flag is a good candidate when all of these are true:

  1. It is a release or experiment flag.
  2. In every environment it serves a single value to everyone, or is off. A flag that is at 100% in Production but still targeted in Staging is not done.
  3. Nothing about it has changed for two weeks or more.

Railflag's flag list has a Stale view that applies the last two rules, and each flag shows its kind, so you can skip ops and permission flags at a glance. Then search the code for the flag key: every repository, including mobile apps and scripts, which may still check it after the web code is gone.

Remove in the right order

The order matters, because an SDK asked for a flag that no longer exists returns the code default, and for an old release flag that default is usually the old behaviour.

  1. Remove the check and the losing code path in one small pull request. Keep the winning behaviour unconditional.
  2. Deploy everything that checked the flag, and wait until old versions are gone, including mobile app versions still in use.
  3. Archive the flag. In Railflag, an archived flag leaves the configuration your SDKs receive, but stays in the audit history and can be restored.
  4. Delete it later if your tool supports it, once you are sure nothing references it.
// Before: the decision was made months ago.
const useNewCheckout = await flags.getBooleanValue('new-checkout', false, ctx);
const checkout = useNewCheckout ? newCheckout : legacyCheckout;

// After: one line, and legacyCheckout is deleted with it.
const checkout = newCheckout;

Keep flag debt from coming back

  • Give every flag an owner and a kind when it is created. A release flag without an owner becomes permanent by accident.
  • Plan removal with the feature. Create the cleanup ticket when you create the flag, due a few weeks after full rollout.
  • Review flags on a schedule, for example in a monthly engineering meeting: walk the Stale view and assign each flag.
  • Make removal easy: one flag check at the edge of a feature, not scattered through dozens of files. See trunk-based development.
  • Let an agent do the typing. With Railflag's MCP server, an AI coding agent can list flags, find the ones that serve one value, and open the pull requests that remove them, while you review.

Frequently asked questions

What is a stale feature flag?
A release or experiment flag that serves the same value to everyone in every environment and has not changed for a while. Its decision is already made, so the flag and the losing code path are dead weight.
Should I delete the flag or the code first?
The code first. Remove the flag check and the losing code path, deploy, and only then archive or delete the flag. If you delete the flag while code still checks it, the SDK returns the code default, which may be the old behaviour.
How many feature flags are too many?
There is no fixed number. What matters is how many flags no longer make a decision. Long-lived kill switches and permission flags are fine in any number if they have owners; release flags that have been at 100% for months are debt.
Which flags should never be cleaned up?
Kill switches (ops flags) and feature gates (permission flags). They look stale because they rarely change, but they are permanent by design. Mark their type so cleanup reviews skip them.

See which flags are done

Railflag's Stale view lists flags that serve one value everywhere and haven't changed in two weeks, with each flag's kind, tags and full history.

Start for free