Feature Flag Pitfalls

Feature flags are easy to add and hard to remove. That asymmetry is the source of most of the pain. Here’s a tour of the ways feature flags go wrong, so you can make informed choices about which mistakes to make.

Zombie Flags

A zombie flag is a flag that should have been deleted months ago but wasn’t. The feature shipped. The experiment concluded. But the flag lives on, because nobody had time to remove it, and now nobody remembers what it does.

Zombie flags accumulate over time. At some point, your codebase is full of if-else branches that will never execute, conditions that are always true, and dead code paths that nobody’s tested in years. It’s technical debt with extra steps.

The fix is simple in principle: treat flag cleanup as part of the feature work, not an afterthought. When you ship a feature, schedule the flag removal. Put it in the ticket. Set a calendar reminder. Do whatever you need to do, but don’t let flags outlive their purpose.

Flag Explosion

One flag is fine. Ten flags is manageable. Fifty flags and you need a spreadsheet just to understand what’s enabled in any given environment. A hundred flags and you have more feature flags than features.

Flag explosion happens when teams add flags without a clear policy on when to remove them. Every new feature gets a flag “just in case,” and none of them ever get cleaned up. Now every deployment requires checking a 200-row configuration table before you can predict what users will see.

Keep a flag registry. Track the purpose, owner, and expected removal date for every flag. If a flag has no owner and no expiry plan, it’s already a zombie in waiting. Or skip the spreadsheet and use a flag management tool that tracks all of this automatically — because the registry you build in a shared doc is the one nobody updates when they’re shipping at midnight.

Testing Complexity

Every feature flag doubles the number of states your system can be in. Two flags means four possible combinations. Ten flags means 1,024. At some point, comprehensive testing becomes mathematically impossible.

In practice, not every combination matters—but some combinations will behave unexpectedly, and you won’t find out until a user hits one in production. The more flags you have active simultaneously, the harder it becomes to reason about what your system actually does.

The mitigation is to minimize the number of active flags at any time. Retire flags aggressively. If you have flags that have been active for more than a quarter without a removal plan, something has gone wrong.

Missing Documentation

“What does EnableSuperMode do?” “No idea, but don’t touch it.”

This conversation happens at every company that uses feature flags without documenting them. The original author left. The ticket was closed. The Slack thread is buried. Nobody remembers what the flag was for or what happens when you flip it.

Every flag should have a name that explains what it does, a description of its purpose, and a clear owner. If you can’t explain a flag in one sentence, it’s not ready to ship.

The Bottom Line

Feature flags are a powerful tool, but they require discipline. Add them intentionally, document them thoroughly, and remove them ruthlessly. A codebase full of forgotten flags is a codebase that’s slowly becoming unmaintainable.

The only good zombie flag is a deleted one.