Keep flags working during an outage
Set up fallbacks and a saved copy of your flags, so your app behaves predictably when the FlagSwift server cannot be reached.
- Time
- About 8 min
- Who can do it
- A developer
- Where
- Your SDK options
- You finish with
- An app that starts and runs correctly with the server down
What and why#
Your flags live on the FlagSwift server, but your app should never depend on that server being up at the moment a user clicks. SDKs are built for this. They download the configuration, keep it in memory and answer every check from there. The server is only needed to refresh, so an outage does not slow a check down or change its answer.
Three layers of protection#
| Layer | Description |
|---|---|
| The last good configuration | Held in memory once loaded. A failed refresh never replaces it. This covers an outage that begins while your app is running. |
| A saved copy | A snapshot file (server SDKs) or a storage adapter (client SDKs), loaded at startup before the network is tried. This covers a restart or deploy during an outage. |
| Fallbacks | Values you choose per flag, served for an unknown flag or when nothing was ever loaded. This covers a first start with no network and no saved copy. |
How a snapshot works#
Each time the SDK applies a new configuration, a server SDK writes it to the file you named (a temporary file, then a rename, so a crash cannot leave half a file, readable by its owner only). On the next start it reads that file first. A file that is corrupt, malformed or from a different hash version is ignored rather than trusted, because a mismatched hash version would put people in the wrong rollout buckets.
Server SDKs and client SDKs differ#
Server SDKs hold the whole configuration and evaluate locally. Client SDKs (browser, mobile) hold only the outcomes the server computed for the current person, so a saved copy is per person and per environment, and identify to a new person while offline uses that person's cached flags if there are any, otherwise it keeps the previous flags.
Before you start#
- An SDK that has loaded its flags once keeps answering without the server. Evaluation reads memory only, so an outage does not slow a check down.
- The risk is the start. An app that starts with no network and nothing saved has no flags yet.
- Pick the SDK you use from
SDK featuresin the reference to see what it can save. The steps below use a server SDK as the example. - A writable directory for the snapshot file, if you use one. If it is read-only, the write is skipped silently and evaluation is unaffected.
Walk through it#
Choose a safe answer for every flag
Set
fallbacks. They are served for an unknown flag and before anything has loaded. A boolean sets on or off. Anything else is served as the value. Pick the answer you would want during a total outage, usually the old behaviour.The order of answers is the flag itself, then the check's own fallback, then your configured
fallbacks, then off. A flag check never throws.Save the last good configuration
Server SDKs write the last configuration to a file when you set
snapshotPath(Go:WithSnapshotPath, Python:snapshot_path, Java:snapshotPath). Use a path that survives restarts, such as a mounted volume, not a container's temporary layer.ts const flags = await FlagSwift.connect({ apiKey: process.env.FLAGSWIFT_KEY!, baseUrl: "https://flags.example.com", environment: "production", fallbacks: { "new-checkout": false }, snapshotPath: "/var/cache/myapp/flagswift.json", });Client SDKs keep the last flags in a storage adapter instead (an object with
getItemandsetItem). JavaScript, React and Vue uselocalStorageby default, which is skipped where the browser blocks it. React Native and Flutter keep nothing across a restart until you pass an adapter.You should see. After the first successful load the snapshot file exists. Its contents are the configuration your SDK downloaded.Or start from data you hold
bootstrap(client SDKs:initialFlags) starts the SDK from a configuration you supply, such as one you saved fromgetSnapshot(). It is ignored if it is malformed or its hash version differs. Server-rendered pages can evaluate on the server and passinitialFlagsso the first render has the right values. Next.js on the server keeps flags in memory per process, so passbootstrapthere for a start that works without the server.ts // Save it yourself, for example to a database or a build artifact const saved = JSON.stringify(flags.getSnapshot()); // Later, start from it const flags = await FlagSwift.connect({ apiKey, baseUrl, bootstrap: JSON.parse(saved) });Bound the startup wait
Startup waits for the first load for at most
initTimeout(5 seconds by default; Python and Java use seconds or milliseconds in their own style) and does not throw when it passes. The fetch carries on in the background and applies when it arrives.The one gap
A start with no network, no snapshot and no bootstrap serves yourfallbacks, then off, until the server is reachable. Nothing in the SDK can close that gap for you.Watch for trouble
Failures never reach your flag checks, but you can see them. Server SDKs have
getStatus()(Go:Status(), Python:get_status()) withinitialized,lastFetchTime,lastErrorandconsecutiveFailures. Client SDKs havegetHealth()withconsecutiveFailures,lastUpdatedand where the current flags came from (source). PassonErrorto log failures.What a server SDK reports in the middle of an outage. Flag checks keep answering from the last good configuration.
What happens while the server is down#
- A failed refresh leaves the last good configuration and its ETag in place. This covers network errors, timeouts, 5xx and 4xx responses, and a reply that is not valid configuration.
- Timeouts, network errors, 429 and 5xx are retried with jittered backoff before a refresh counts as failed (the JavaScript and Node SDKs retry 3 times for a server SDK and 2 for a client SDK, with a 5 second timeout per attempt). The SDK honours
Retry-After, and other 4xx responses fail at once. - The SDK records the failure for its health report and its error callback. It does not throw out of a flag check.
- While polling keeps failing, the delay between attempts doubles each time, with 20 percent jitter, up to the larger of your refresh interval and 5 minutes in the JavaScript and Node SDKs, and it resets after the first success. Exact timings differ by SDK, so check yours in the reference.
- Client SDKs:
identifywhile offline uses the new person's cached flags if there are any. Otherwise it keeps the previous flags. - PHP and Laravel cannot be fully non-blocking when the stored copy is stale and the server is down. They make one capped attempt per backoff window.
- When the server returns, the SDK picks up the current configuration on its next successful poll, or at once if streaming reconnects. No restart is needed.
Good to know#
Make the fallback the safe choice, not the new feature
true turns a new feature on for everyone during an outage, including the people you had not rolled it out to. Prefer the old behaviour. The exception is a kill-switch style flag where “on” means “protect the system”.Is the snapshot a secret?
How old can a snapshot be?
Does the kill switch work offline?
Do I need both snapshotPath and bootstrap?
bootstrap it is used instead of reading the snapshot file at startup, and the file is still updated as new configuration arrives.What to check#
- Start your app, stop the FlagSwift server, and confirm flag checks still return the same values.
- Restart the app with the server still stopped and confirm it serves the saved values, not only your fallbacks.
- Delete the snapshot and restart with the server stopped. Confirm your fallbacks are served and nothing crashes.
- Start the server again and confirm the SDK picks up the current flags without a restart.
If something goes wrong#
After a restart with the server down, every flag is off
Why: No snapshot, bootstrap or cache was available, so the SDK served your fallbacks and then off.
Fix: Set snapshotPath to a path that persists across restarts and confirm the file exists after a successful run.
The snapshot file is never created
Why: The directory is read-only or the process cannot write there. The SDK skips the write silently so evaluation is not affected.
Fix: Use a writable path, such as a mounted volume, and check permissions for the app user.
The snapshot is ignored on start
Why: The file is corrupt, is not valid configuration, or was written by a server on a different hash version.
Fix: Delete it and let the SDK write a fresh one after the next successful load.
Browser or mobile app shows default values after a restart offline
Why: The storage adapter is missing (React Native, Flutter) or the browser blocks localStorage (private mode).
Fix: Pass a storage adapter, or provide initialFlags from the server.
Start-up feels slow when the server is down
Why: The SDK waits up to initTimeout for the first load.
Fix: Lower initTimeout. The load carries on in the background and applies when it succeeds.