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.executeto lock andkill_switch.restoreto 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#
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 Part Description 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. Impact States how many flag settings across how many flags will be turned off and locked, and how many are serving traffic right now. Confirmation Type DISABLEto 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 asKill 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 saysThe kill switch is active here, so this flag is off for everyone whatever is set below.The inspector givesKILL_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.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.
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.
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 asKill switch lifted on 6 flag settings: 4 turned back on, the rest were already off. The inspector no longer reportsKILL_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.
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"
}'{
"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.
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_SWITCHwhile 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