Skip to content
FlagSwiftDocs

Find and remove stale flags

Find the flags nobody needs any more, check that your code no longer reads them, and archive them before they become dead branches.

Time
About 8 min
Who can do it
Developer, Release manager or Admin to archive. Admin to delete for good.
Where
Flag lifecycle in the console, then a flag's Lifecycle and Advanced tabs
You finish with
Finished flags archived, and the code that read them already removed

What and why#

What a stale flag is#

A flag is stale when it has stopped doing work: it has been off everywhere, fully on for everyone, or unread for at least 14 days. Its code path is now dead weight, and each one makes the next change harder to reason about.

How cleanup works here#

The Flag lifecycle list works out a status and a removal verdict for every flag from its configuration, its recent evaluations, a scan of your code and the flags that depend on it. You remove the flag from code first, then archive it, and only delete it for good when you are sure.

Why archive before deleting#

Archiving hides the flag and stops serving it, but keeps its configuration and history, and you can restore it at any time. Deleting is permanent.

Before you start#

  • Run the code scanner at least once, so removal advice can tell whether code still uses a flag. See Link flags to your code. Without it, the best verdict is Potentially safe.
  • Permission to archive flags (flags.archive): Developers, Release managers and Admins. Deleting for good (flags.delete) is for Admins only.
  • Evaluation history, which is kept for 30 days by default. A flag no SDK evaluated in that window looks unused.

Walk through it#

  1. Open the list

    Open Flag lifecycle, choose the Project and set Show to Needs attention. That covers stale, expiring, expired and removal due flags. Narrow it with Owner or the search box. The note under the tiles says where evaluation history begins and whether any repository has reported code references.

  2. Read the removal verdict

    Each row has a verdict and a one-sentence reason, such as Flag has been OFF for 120 days. Potentially safe to remove.

    Needs attention in the Web app project. The tiles count flags; the note under them says whether code has been scanned.
    Removal verdicts
    VerdictDescription
    Safe to removeOff, fully on or unused for 30 days or more, and a scan found no references.
    Potentially safe to removeThe same, but no repository has reported yet, so use in code is unknown.
    Not safe to removeCode still uses it, or another flag lists it as a prerequisite. This always wins.
    Not ready to removeStill changing or rolling out, marked permanent, or off, fully on or unused for fewer than 30 days.
    You should see. An archived flag with no references reads “Archived and no code references were found. Safe to delete.”
  3. Check the owner and the code

    Open a flag from its name and go to its Lifecycle tab. Code references lists each repository and the files and lines that read the flag. For a flag with an owner, ask them before you remove it. Remove the flag from code first, deploy, and let the next scan run so the references clear.

  4. Archive

    Tick the flags and choose Archive selected, or use Archive on one row, then confirm. You can archive up to 50 at once, and each flag is attempted on its own, in order. Archived flags stop being served, so SDKs fall back to their default value. A flag that is another flag's prerequisite is skipped and reported, and the rest still archive.

    Selecting rows reveals the bar with Archive selected, and the confirmation names how many flags are involved.
    You should see. The archived flags leave the list and appear under Show: Archived.
  5. Delete when you are sure

    Admins only. Open the archived flag, go to the Advanced tab and choose Delete permanently. If code still uses the flag, the dialog lists the places (up to 20) and you must switch on Delete it anyway, because that code will fall back to its default. Then type the flag key to confirm. To bring a flag back instead, choose Restore flag on the same tab.

    Delete permanently for an archived flag that code still uses. The confirm button stays disabled until Delete it anyway is on and the key is typed exactly.

Unused is not proof

A flag read only by an SDK that does not report evaluations, or before the history starts, can look unused. Keys built at runtime, such as checkout-${name}, cannot be found by the scanner. Mark those flags permanent or keep them out of cleanup.

Do it with the API#

List what needs attention, then archive in bulk

Both are Dashboard API calls that act as the signed-in person. Each result says whether that flag was archived, so one refusal does not stop the others. The list call also returns counts for every filter, the project's codeScan state and collectingSince. See the Lifecycle API.

Request
# Flags that need attention in a project (flags.read, session cookie)
curl -s "https://flags.example.com/api/lifecycle?projectId=PROJECT_ID&filter=attention&limit=25" -b jar.txt

# Archive several flags at once (flags.archive). Up to 50 ids.
curl -X POST "https://flags.example.com/api/lifecycle/archive" \
  -b jar.txt -H "Content-Type: application/json" \
  -d '{"ids":["FLAG_ID_1","FLAG_ID_2","FLAG_ID_3"]}'
Bulk archive response
{
  "status": "success",
  "message": "Some flags could not be archived",
  "data": {
    "results": [
      { "id": "FLAG_ID_1", "ok": true },
      { "id": "FLAG_ID_2", "ok": true },
      { "id": "FLAG_ID_3", "ok": false, "error": "Cannot archive \"Payments v2\": it is a prerequisite of Express pay (production). Remove the dependency first." }
    ],
    "archived": 2,
    "failed": 1
  }
}

What to check#

  • The archived flags move to the Archived filter.
  • Your applications still run, and the Errors page shows no new unknown flag keys.
  • Anything that was skipped has a prerequisite to remove first.

Good to know#

Do it on a routine

Review the Needs attention list at the start of each sprint. Small, regular cleanups are safer than a quarterly purge, and the 30-day wait before a verdict turns green gives you time to catch a flag that was only between releases.
Why does a flag I use show as stale?
Stale also covers flags that are on for everyone in every environment and unchanged for 14 days. That is a finished rollout: the next step is to delete the check and the flag. Mark the flag permanent if it should stay.
Can I archive from the flag instead of the list?
The Advanced tab, which holds Archive flag, is offered to Admins. Developers and Release managers archive from this list or with the API.
What happens to apps that still read an archived flag?
They get their fallback value (or false). Nothing throws, but behaviour can change, which is why you remove the code first.
Can I undo an archive?
Yes. Open the archived flag and choose Restore flag, or call the restore endpoint. It returns with the configuration it had.

If something goes wrong#

Some flags could not be archived

Why: Another flag lists it as a prerequisite (FLAG_IS_PREREQUISITE), or the project is archived. The result names the flags that depend on it.

Fix: Open the flag named in the message, remove the prerequisite on its Targeting & rollout tab, then archive again.

Archive up to 50 flags at a time

Why: A bulk request carried more than 50 ids.

Fix: Archive in batches of 50 or fewer.

Every flag says Potentially safe, never Safe

Why: No repository has reported code references for this project yet.

Fix: Run the scanner from CI. The advice changes to Safe once a repository has reported and found no references.

This flag is still used in N places in code (HAS_CODE_REFERENCES)

Why: A delete was refused because the last scan found references.

Fix: Remove the code and let the next scan run, or confirm Delete it anyway.

A flag I know is unused is not in Needs attention

Why: It is under 14 days old, marked permanent, or evaluated recently by an SDK.

Fix: Open its Lifecycle tab and read the findings. Set an expected removal date to make it surface on a date you choose.