Skip to content
FlagSwiftDocs

Handle an incident with the kill switch

When a flag is causing harm, stop it first, work out what changed second and put it back once the cause is fixed.

Time
About 6 min
Who can do it
Release manager or Admin (kill_switch.execute). Developers have it outside production only.
Where
Flags > Activate Kill Switch
You finish with
Flags off and locked, the cause found, and the lock lifted safely

What and why#

What it is#

The kill switch turns flags off and locks them in the environments you choose, in one action. A locked flag evaluates to off for everyone with the reason KILL_SWITCH, whatever its targeting says, and nobody can switch it back on by accident until you lift the lock. It is the first move in an incident: it stops the harm in seconds and buys you time to find the cause.

When to use it#

  • Errors or latency jump right after a release and a flag is the likely cause.
  • A feature is exposing something it should not and you need it off now, before you know why.
  • You need to stop many flags at once, such as every flag in a project in production.

How it works#

For each flag and environment you pick, FlagSwift remembers whether it was on, turns it off and marks it locked. SDKs pick the change up on their next update. Lifting the lock puts each flag back to whether it was on or off when the lock began. It is never held up by approval, even where production requires it.

Before you start#

  • Know who can use the kill switch before you need it. It needs kill_switch.execute to lock and kill_switch.restore to lift. Release managers and Admins have both everywhere. Developers have them outside production and are withdrawn from them in production. Product managers and Viewers do not have them. See Give people the right access.
  • Know which environment you are stopping. The lock is scoped to the environments you choose, so stopping Staging does not help Production.
  • Know the scope. The button on the Flags page covers the project you have selected there. Choose the project first.

Walk through it#

  1. Stop the flags

    Open Flags, select the project and choose Activate Kill Switch at the top right. The button appears only if you have kill_switch.execute. A dialog titled Activate kill switch opens with Disable & lock chosen. Work down it:

    The kill switch dialog
    PartDescription
    1. Which environments?Tick one or more. Select all and Clear help. Each shows how many flags are on now. An environment with nothing to change is greyed out with Nothing to change here.
    2. Which flags?Every flag in the project (the default), or Only the flags I choose with a search box, Select shown and Clear. The list loads the first 100 flags. Choosing every flag still covers all of them.
    3. Why? (optional)Up to 300 characters, saved in each flag's history and the audit log, such as Checkout errors spiking, see incident #142.
    ImpactStates how many flag settings across how many flags will be turned off and locked, and how many are serving traffic right now.
    ConfirmationType DISABLE to confirm. This guards against a stray click and applies to locking only.

    Choose Disable & lock, which shows the number of settings in brackets.

    The kill switch dialog before you confirm. The button stays off until DISABLE is typed.
    You should see. A message such as Kill switch on: 6 flag settings disabled and locked. The flags show Kill switch instead of a toggle, the button now reads Disable Kill Switch with a count, and the flag's Targeting tab says The kill switch is active here, so this flag is off for everyone whatever is set below. The inspector gives KILL_SWITCH.

    Review does not slow this down

    The emergency stop and rollback are never held up by approval, even when production requires it. Other members who can use the kill switch are sent an email telling them it was activated and by whom.
  2. Find out what changed

    Open the flag's History & rollback tab and read Activity for toggles, rollout and targeting changes, then open Events and the audit log to see who changed what and when, and compare it with when the problem started. The audit log can be exported as CSV or JSON for the review afterwards. See Review the audit log and event feed.

  3. Put the safe configuration in place

    While a flag is locked you cannot toggle it and you cannot roll it back, but you can still edit its rollout, targeting and rules. Two ways to get the good configuration back:

    • Edit the configuration by hand while it is locked, for example set the rollout percentage back to what it was, then lift the lock.
    • Lift the lock, then roll back from History & rollback straight away. A rollback restores the earlier version as a new version and is refused while the lock is active. Expect a short moment when the flag is back on with the current configuration.

    See Review history, compare versions and roll back.

  4. Lift the lock

    Choose Disable Kill Switch (the same button, now showing how many settings are locked). The dialog opens on Lift the lock. Choose the environments and flags, add a reason and choose Lift the lock. No typed confirmation is needed. Each flag goes back to whether it was on or off when the lock began: those that were on turn back on, and those that were already off stay off.

    The same dialog in lift mode. Environments show how many flags are locked, and no confirmation is typed.
    You should see. A message such as Kill switch lifted on 6 flag settings: 4 turned back on, the rest were already off. The inspector no longer reports KILL_SWITCH.

    Watch Errors and Metrics for a few minutes before you widen anything again.

Do it with the API#

Activate or lift the kill switch

This is a Dashboard endpoint, so it authenticates with your signed-in session cookie (auth_session), not an API key. It needs kill_switch.execute (and kill_switch.restore for mode restore), and the environments you name are checked, so a Developer is refused for production. environments takes 1 to 50 names. flagIds (up to 500) narrows it to specific flags. Leave it out to cover every active flag, or give projectId to narrow it to one project. reason is up to 300 characters. The result counts what changed and what was skipped because it was already in that state.

Request
curl -s -X POST "https://flags.example.com/api/flags/kill-switch" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "activate",
    "environments": ["production"],
    "projectId": "PROJECT_ID",
    "reason": "Checkout errors spiking, incident 142"
  }'
200 OK
{
  "status": "success",
  "message": "Kill switch activated",
  "data": {
    "mode": "activate",
    "flagsAffected": 6,
    "changed": 6,
    "wasEnabled": 4,
    "restored": 0,
    "skipped": 0
  }
}

Lift the lock for one flag

Send mode restore with the same environments. Name flags in flagIds to lift only those. The result reports how many were restored and how many were skipped because they were not locked.

Request
curl -s -X POST "https://flags.example.com/api/flags/kill-switch" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "restore",
    "environments": ["production"],
    "flagIds": ["FLAG_ID"],
    "reason": "Fix deployed in release 2.14"
  }'

Roll back afterwards with the endpoints in Review history, compare versions and roll back. See the Emergency stop reference.

What to check#

  • Evaluate the flag from the inspector and confirm the reason is KILL_SWITCH while it is stopped.
  • Errors falls after the stop and does not come back when you lift it.
  • The stop, any rollback and the lift each appear in the audit log with a name and a time. Locking and lifting are recorded as one event per environment, and the flag's own History shows the detail per flag.

If something goes wrong#

I cannot see Activate Kill Switch

Why: Your role has no kill_switch.execute permission, or the project has no environments.

Fix: Ask a Release manager or an Admin, or check the project has environments.

Forbidden when stopping a production environment

Why: Developers are withdrawn from the kill switch in production.

Fix: A Release manager or an Admin does it.

Nothing to do: these flags are already locked or not set up here

Why: Every chosen flag is already locked, or has no configuration in the chosen environments.

Fix: Pick other environments or flags. An environment greyed out with Nothing to change here has nothing to lock.

Cannot roll back while the kill switch is active

Why: A rollback never restores the stop, so it is refused while it is on.

Fix: Lift the lock first, or put the safe configuration in by hand while it is locked.

Cannot toggle flag while the kill switch is active for this environment

Why: Toggling is blocked on a locked flag.

Fix: Lift the lock, then toggle.

The Disable & lock button stays off

Why: No environment is ticked, no flag is chosen, or you have not typed DISABLE.

Fix: Fix whichever of the three the impact box points at.

The app still shows the feature after the stop

Why: The SDK has not picked up the change yet, or it is serving a cached configuration.

Fix: Wait for the next poll or check streaming. See Get changes in real time with streaming.

Good to know#

Lifting does not undo the cause

Lifting the lock restores each flag to how it was on or off, with its current configuration. If a bad rollout percentage or rule caused the incident, fix or roll that back first, or the problem returns the moment the flag is back on.
Does the kill switch delete or change my targeting?
No. It turns each flag off, locks it and remembers what was on. Targeting, rules, segments and percentages are untouched.
Can I stop one flag only?
Yes. In the dialog choose Only the flags I choose and tick that flag. Through the API send flagIds.
What happens to a flag created while the lock is on?
It is not locked. The lock applies to the flags and environments chosen when it was activated, and a later one-off lock covers new ones.
Will my team be told?
Other members who can use the kill switch are emailed when it is activated or lifted. Both are in the audit log. You can also set up an alert. See Set up alerts.