Feature Flag Debt: How to Find, Remove and Prevent Stale Flags

A flag that's been on for everyone for a year looks harmless. It isn't:

• Dead code paths. The old branch still exists, still needs to compile and confuses anyone reading the file.
• Untested combinations. With several flags, the number of possible states grows faster than any test suite covers. Only one state is in production, and the rest are guesses.
• Accidental toggles. Someone flips an old flag and revives a path nobody has run in months.
• Slower reviews and onboarding. Every conditional is something a reader must understand.
• Platform clutter. Long lists hide the flags that matter, including operational kill switches.

The risk is concrete: if someone reuses an old flag name or flips a forgotten flag, code that nobody has run in months can come back to life in production. Unused conditional paths are liabilities.

Start with a short audit:

1. Export every flag with its type, owner, creation date, environments and last change.
2. Flag candidates where a release or experiment flag has been at the same value in all environments for a set period, such as one full release cycle after reaching everyone.
3. Check for no evaluations, which means the code no longer asks for the flag, so the flag itself can go.
4. Search the code for each flag key, and list references, including tests and config.
5. Ask the owner. If the owner has left, assign the flag to the team that owns the code area.

Some flags shouldn't be removed. Operational kill switches and entitlement flags are meant to be long-lived, so label them as permanent, with an owner, so they don't appear in every cleanup sweep. A flag platform such as LaunchDarkly may report which flags haven't changed or been evaluated lately, so ask in a demo whether it does; that would speed up this audit.

Removal is a normal code change and deserves the same care:

1. Confirm the winning value. For a release flag, it's the on path. For an experiment, use the result.
2. Remove the conditional and keep only the winning path, including any helper code used only by the loser.
3. Update tests. Delete tests of the losing path and check that the winning path is still covered.
4. Deploy and observe. Ship the code change with the flag still defined in the platform, so an old server or client that still asks for it gets a value.
5. Delete the flag in the platform after deployment is complete everywhere, including mobile clients that update slowly.
6. Close the ticket and note the removal.

Order matters. Deleting the flag first can make code fall back to its default and change behavior in production.

Prevention is cheaper than cleanup:

• Create a removal task when you create the flag. Put it in the same ticket, with a target date.
• Require metadata: owner, purpose and expiry for release and experiment flags.
• Name flags by type, so temporary ones are obvious. The naming convention guide shows one approach.
• Set a limit. For example, agree that a release flag should be removed within a couple of weeks after reaching everyone, and flag exceptions in the weekly review.
• Schedule a recurring sweep. One engineer spends an hour each month on the audit list.
• Report the numbers. Track flag count by type and age, and show the oldest ten in the team channel.

Flags used for staged exposure should end with removal, as the canary release playbook describes.

Say a team audits its flag list and finds a mix of forty flags. Most are release flags left over from past launches, a few are experiments, and a handful are kill switches.

They sort the list into three piles. Kill switches are labeled permanent and given owners. The experiments with clear results become removal tickets with the winning variant noted. The release flags at full exposure for over a cycle go into a batch of small pull requests, each removing one flag, so review stays easy and a bad change can be reverted alone.

After removing the code, they delete the flags in the platform and record the count. Then they add a required expiry field to the flag creation template. The first sweep is the biggest; after that, monthly maintenance takes a fraction of the time. For platform selection and features that help with this, see the LaunchDarkly, Split and Flagsmith comparison.