Flag debt

Also called: feature-flag debt, toggle debt

Last updated:

Flag debt is the form of technical debt created when feature flags pile up faster than they are retired. Every flag is a branch in the code and a row in the configuration. Once its decision is made (the rollout finished, the experiment concluded), the flag becomes dead weight that engineers still have to read around, test, and reason about. Flag debt is the sum of those un-retired flags.

Where flag debt comes from

Most flags are temporary by intent but permanent by neglect. A percentage rollout reaches 100% and nobody deletes the flag. An A/B test ends and the losing branch lingers. A feature is abandoned behind an off switch. Each survivor is a stale flag, and stale flags are what flag debt is made of. The cost compounds: more branches to test, more states to reason about, and a real outage risk when someone misreads which path is live. The Knight Capital trading failure began with logic left behind a flag that should have been retired.

Paying flag debt down

The fix is lifecycle discipline: treat every temporary flag as carrying a removal task, and make retiring flags routine rather than heroic. The hard part is knowing which flags are safe to remove, so Featureflip classifies each one as Active, Stale, or Dead from real flag evaluation traffic, so the cleanup queue builds itself instead of waiting on an audit. See the stale flag detection guide for the model, and a practical flag-cleanup workflow for retiring them safely. Where that removal is handed to automation, the useful question becomes which rewrites a tool should decline to make.

Want the full picture? Read the concept guide: Stale flag detection →

Related terms

Stale flag

A stale flag is a feature flag that no longer makes a live decision (it serves one variation to everyone, receives no traffic, or was never used) yet still exists as a conditional branch in code.

Feature flag

A feature flag is a conditional in your code whose value is controlled from a remote dashboard, letting you turn functionality on or off without deploying new code.

Flag evaluation

Flag evaluation is the process an SDK runs to decide which variation a feature flag returns for a given user, applying prerequisites, targeting rules, and rollouts to the user context.

Browse the full feature flag glossary →

Try it in your own app

The Free plan covers 10 flags and 2 environments. No credit card, no demo call — sign up and ship.

Get started free See pricing