Skip to content
NanoFlags
Start free

Reference

Kill switch

When a flag breaks production, the kill switch serves the flag's off value right away — in one environment or in all of them — without opening a change or waiting for an approver. Turning the flag back on goes through the normal reviewed path.

What it does

Using the kill switch publishes a new, signed revision of the environment, marked as an emergency revision (kind: "kill"). It contains exactly what was already published, with one difference: the flag you chose is turned off, so every SDK serves its published off value. It is distributed like every other revision, so connected SDKs usually apply it within a second (in our production check, a median of 178 ms from commit to the SDK's update event).

  • Skipped for this one revision: the requirement to publish through a change, approvals, and scenario checks.
  • Not skipped: your role, two-step verification where your organization requires it, a typed reason, the rate limit, and the audit log.
  • Nothing else changes: other flags and segments stay as published, and pending draft work is not published.
  • Environments where the flag is not published, already off or already killed are skipped and reported.

Who can use it

By default, owners and admins. An owner can change this under Settings → Organization → Kill switch to owners only, or to owners, admins and editors. Viewers can never use it. If the organization requires two-step verification, everyone who uses the kill switch must have verified with an authenticator in the current session, editors included, because it bypasses review.

From the dashboard

Open the flag and choose Kill switch. The dialog shows the environments (the one selected in the sidebar, or every environment where the flag is on), what users get now and after the kill (the off value per environment), and asks for a reason. After confirming, the flag page and the flags list show the flag as Killed in that environment, with who killed it, when, and why.

What happens to your draft

The draft is kept and rebased on the kill: the flag is also turned off in the draft of each killed environment, and every other pending edit (including the flag's own rules and values) stays. A later normal publish therefore cannot silently turn the flag back on. Two consequences to expect:

  • Approvals given to the previous draft become stale, because the reviewed content changed. Approve again after the incident.
  • A pending scheduled publish of that environment fails safely (the draft and the destination revision it pinned have changed); schedule it again.

Turning it back on

Choose Restore on the flag page (editor role). This turns the flag on in the environment's draft and opens a change for it. Publish that change as usual: it needs the approvals and scenario checks the environment requires. The flag stops being shown as killed once a revision serves it enabled again, whoever publishes it.

Management API

Both calls need an API token with the flags:kill scope. The scope is never implied by flags:write or publish. Send an Idempotency-Key so a retried request cannot kill twice. See the Management API reference for every field and error.

sh
curl -X POST https://edge.nanoflags.io/api/v1/projects/commerce/flags/new-checkout/kill \
  -H "Authorization: Bearer $NANOFLAGS_API_TOKEN" \
  -H "Idempotency-Key: incident-4711" \
  -H "Content-Type: application/json" \
  -d '{ "environment": "production", "reason": "Checkout errors spiking since the 14:00 release" }'

# then, after the incident: open the reviewed restore change
curl -X POST https://edge.nanoflags.io/api/v1/projects/commerce/flags/new-checkout/restore \
  -H "Authorization: Bearer $NANOFLAGS_API_TOKEN" -H "Content-Type: application/json" \
  -d '{ "environment": "production" }'
StatusCodeMeaning
403FORBIDDENThe token's creator does not have the organization's kill-switch role.
403INSUFFICIENT_SCOPEThe token lacks flags:kill.
409ALREADY_KILLEDThe flag is already killed in the chosen environment(s).
409NO_CHANGESThe flag is not published, or already off, there.
422REASON_REQUIREDThe reason is missing or shorter than 8 characters.
429RATE_LIMITEDToo many kills (see below).

CLI

sh
export NANOFLAGS_API_TOKEN=nf_api_…        # token with the flags:kill scope
nanoflags flags kill new-checkout --env production --reason "Checkout errors spiking since the 14:00 release"
nanoflags flags restore new-checkout --env production

Add --project <key> when the token can see several projects, --all-environments instead of --env to kill everywhere, and --json for machine-readable output. See CLI.

Notifications and audit

  • Every owner and admin of the organization receives an e-mail right away (it cannot be turned off), with the flag, the environments, the reason and who used it.
  • Webhook events flag.killed (one per environment) and flag.kill_restored, plus the usual publish.completed for the new revision. See Webhooks.
  • The audit log records flag.killed with the reason, the new and previous revision and the off value, and the revision appears in the history with its note.

Safeguards

  • A person can use the kill switch at most 5 times in 10 minutes, and an organization at most 20 times an hour.
  • An organization that is suspended cannot publish, including with the kill switch; the configuration already published keeps being served.
The kill switch only changes what the flag serves. If the problem is in code that does not check the flag, roll back the deployment as well.