Skip to content
FlagSwiftDocs

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#

What protects you, in order
LayerDescription
The last good configurationHeld in memory once loaded. A failed refresh never replaces it. This covers an outage that begins while your app is running.
A saved copyA 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.
FallbacksValues 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.
Which layer answers a flag check. The first row that applies wins.

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 features in 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#

  1. 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.

  2. 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 getItem and setItem). JavaScript, React and Vue use localStorage by 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.
  3. Or start from data you hold

    bootstrap (client SDKs: initialFlags) starts the SDK from a configuration you supply, such as one you saved from getSnapshot(). It is ignored if it is malformed or its hash version differs. Server-rendered pages can evaluate on the server and pass initialFlags so the first render has the right values. Next.js on the server keeps flags in memory per process, so pass bootstrap there 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) });
  4. 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 your fallbacks, then off, until the server is reachable. Nothing in the SDK can close that gap for you.
  5. Watch for trouble

    Failures never reach your flag checks, but you can see them. Server SDKs have getStatus() (Go: Status(), Python: get_status()) with initialized, lastFetchTime, lastError and consecutiveFailures. Client SDKs have getHealth() with consecutiveFailures, lastUpdated and where the current flags came from (source). Pass onError to 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: identify while 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

A fallback of 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?
It contains your flag configuration, including targeting rules, so treat it like configuration. It is written readable by its owner only. Keep it out of images you share. Client SDK caches hold only outcomes, not rules.
How old can a snapshot be?
As old as the last successful refresh. There is no expiry. A flag that was turned off during the outage still reads as on from the snapshot until the server is back.
Does the kill switch work offline?
It is a server-side change, so an app cut off from the server cannot see it. It takes effect on the next successful refresh.
Do I need both snapshotPath and bootstrap?
No. If you pass 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.