> ## Documentation Index > Fetch the complete documentation index at: https://launchdarkly.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Flag overrides **Developer** **Federal docs** **EU docs** This topic explains how to use flag overrides in server-side SDKs. A flag override forces a flag or segment to a definition that you supply in a local file. The override takes effect in a running application without a restart or a redeploy, whether or not the SDK can reach LaunchDarkly, and it stays in effect until you remove it. > [!NOTE] > > **Flag overrides are experimental** > > Flag overrides are available in the SDKs listed below. This feature is experimental and subject to change. > > Flag overrides use [data saving mode](https://launchdarkly.com/docs/sdk/features/data-saving-mode.md), which is only available to members of the LaunchDarkly Early Access Program (EAP). ## About flag overrides Flag overrides are for incidents. Use an override when you need to change a flag in a running application and you cannot make the change through LaunchDarkly. For example, the SDK might not be able to reach LaunchDarkly and is serving flag data that is out of date, or you might not be able to edit the flag in LaunchDarkly. An override applies only to the flags and segments it defines. The SDK continues to use LaunchDarkly data for every other flag. This is the difference from [reading flags from a file](https://launchdarkly.com/docs/sdk/features/flags-from-files.md), which replaces the connection to LaunchDarkly for all flags. Overrides behave as follows: * An override takes precedence over LaunchDarkly data for its key. This includes evaluations that use the flag as a prerequisite and evaluations that use the segment in a rule. * The SDK serves overrides before it receives any data from LaunchDarkly. An override works even if the SDK never connects. * Overrides that are in the files when your application starts are in effect after the SDK client finishes starting. * The SDK does not serve overrides in [offline mode](https://launchdarkly.com/docs/sdk/features/offline-mode.md). * An override stays in effect even after LaunchDarkly becomes available again. While a flag has an override, changes that you make to the flag in LaunchDarkly do not affect its evaluations. You can configure the override source ahead of time. It has no effect until an override file contains entries. We recommend that you keep overrides short-lived. Add the override, make the same change in LaunchDarkly, confirm the flag's configuration in LaunchDarkly, and then remove the override. ## Prerequisites To use flag overrides, you need: * An SDK version that supports flag overrides. Each SDK section below lists the required version. * An SDK configured for [data saving mode](https://launchdarkly.com/docs/sdk/features/data-saving-mode.md). The override source is part of the data system configuration. If your application already configures the data system, add the override source to that configuration. If it does not, set up data saving mode first, and configure any persistent store or Relay Proxy settings through the data system configuration. ## Create an override file Override files use the same format as [flag data files](https://launchdarkly.com/docs/sdk/features/flags-from-files.md#create-a-flag-data-file). Each file is a JSON or YAML document with up to three properties: * `flagValues`: Flag keys mapped to values. The SDK serves the value to every context. It evaluates the entry as a flag that is on and serves the value as its fallthrough. The evaluation reason kind is `FALLTHROUGH`. * `flags`: Full flag definitions, keyed by flag key. These can target contexts and use rules, prerequisites, and segments. * `segments`: Segment definitions, keyed by segment key. Here is an example: ```json title="JSON" lines wrap theme={null} { "flagValues": { "my-boolean-flag-key": false, "my-string-flag-key": "value-1" }, "flags": { "my-targeted-flag-key": { "key": "my-targeted-flag-key", "on": true, "variations": [ true, false ], "targets": [ { "values": [ "context-key-123abc" ], "variation": 0 } ], "fallthrough": { "variation": 1 }, "offVariation": 1 } } } ``` ```yaml title="YAML" lines wrap theme={null} flagValues: my-boolean-flag-key: false my-string-flag-key: "value-1" flags: my-targeted-flag-key: key: my-targeted-flag-key "on": true variations: [ true, false ] targets: - values: [ "context-key-123abc" ] variation: 0 fallthrough: variation: 1 offVariation: 1 ``` With these overrides, `my-boolean-flag-key` serves `false` and `my-string-flag-key` serves `"value-1"` to every context. `my-targeted-flag-key` serves `true` to the user context with the key `context-key-123abc` and `false` to every other context. To override a flag and keep its targeting, start from the flag's current definition. Download your flag data from the `/sdk/latest-all` endpoint, as described in [Create a flag data file](https://launchdarkly.com/docs/sdk/features/flags-from-files.md#create-a-flag-data-file), and copy the flag's entry from `flags`. Do not use the `/sdk/poll` endpoint: its output is not in the file format. > [!WARNING] > > **Quote YAML names that a parser can read as booleans or numbers** > > Some YAML parsers read an unquoted name such as `on` as the boolean `true`, and a name such as `2024` as a number. A flag definition with an unquoted `on` property evaluates as if the flag is off, and a flag key that a parser reads as a number can make the whole file fail to load. Write the property name as `"on"`, as the YAML example does, and quote flag keys and segment keys that look like booleans or numbers. A `flagValues` entry is not available to client-side SDKs. If you bootstrap a client-side SDK from the server-side SDK's [all flags](https://launchdarkly.com/docs/sdk/features/all-flags.md) output, override the flag in `flags` with a definition copied from LaunchDarkly. That preserves the flag's client-side availability settings. If you write the definition yourself, set both `"clientSide": true` and `"clientSideAvailability": { "usingEnvironmentId": true }`, because SDKs read different properties. ### Use multiple files You can configure more than one override file. The SDK combines the entries from all the files, in the order you list them. If the same flag key or segment key appears in more than one file, the SDK rejects the change by default and keeps the overrides it loaded last. You can configure the SDK to use the entry from the first file that defines the key instead. A configured file that does not exist contributes no overrides. You can create the file when you need it. Deleting the file removes its overrides. ### Change and remove overrides The SDK reads every configured file again when any of them changes. Removing an entry from a file removes that override. If a file exists but the SDK cannot read or parse it, the SDK keeps the overrides it loaded last, logs an error, and tries again. The SDK detects changes in one of two ways: * **Polling**: The SDK checks the files for changes every second. This is the default. Polling works on every file system, including network file systems and directories whose contents are replaced through symbolic links, such as a Kubernetes ConfigMap mounted as a volume. You can make the polling interval longer. The minimum is one second. * **Watching**: The SDK reloads the files when the file system reports a change. This is faster than polling, but some file systems do not report changes reliably. When the client starts and each time the overrides in effect change, the SDK logs at the info level how many flag and segment overrides are in effect and how many each file supplied. ## How overrides affect evaluations and events An evaluation is affected by an override when it reads a definition from an override file. This includes evaluations of a flag with a prerequisite at any depth that has an override. It also includes evaluations of a flag with a rule that uses a segment that has an override. An evaluation that is affected by an override works like this: * The [evaluation reason](https://launchdarkly.com/docs/sdk/features/evaluation-reasons.md) has the `overrideAffected` property set to `true`. The reason kind is the kind that the definition produces. If the evaluation fails, for example because of a type mismatch, the reason is an error reason that still has `overrideAffected` set to `true`. * The SDK does not send feature events or debug events for the evaluation, even if the flag configuration requests them. LaunchDarkly features that rely on feature events, such as Experimentation, do not receive data from these evaluations. * The SDK counts the evaluation in the summary events it sends to LaunchDarkly, separately from evaluations that are not affected by an override. * In the [all flags](https://launchdarkly.com/docs/sdk/features/all-flags.md) output, an overridden flag is evaluated from its override, and every flag that is affected by an override has event tracking turned off. A flag that exists only in an override file is included. Overrides do not remove any other flag from the output. Adding, changing, or removing an override notifies [flag change listeners](https://launchdarkly.com/docs/sdk/features/flag-changes.md) in the same way that a change from LaunchDarkly does, including listeners for flags that depend on the overridden flag or segment. ## Server-side SDKs This feature is available in the following server-side SDKs: * [Go](#go) * [Node.js (server-side)](#node-js-server-side) ### Go > [accordion] Expand Go code sample > > To use flag overrides, configure the data system with a file-based override source. > > > [!NOTE] > > > > **Supported versions** > > > > Flag overrides are available in the Go SDK version 7.18 and later. In versions 7.18 and 7.19, a `flagValues` entry evaluates with the `OFF` reason kind instead of `FALLTHROUGH`. > > This example reads overrides from `/etc/launchdarkly/overrides.json`: > > ```go title="Go SDK v7.18+" lines wrap theme={null} > import ( > "time" > > ld "github.com/launchdarkly/go-server-sdk/v7" > "github.com/launchdarkly/go-server-sdk/v7/ldcomponents" > "github.com/launchdarkly/go-server-sdk/v7/ldoverrides" > ) > > var config ld.Config > > config.DataSystem = ldcomponents.DataSystem().Default(). > Overrides(ldoverrides.FileSource().FilePaths("/etc/launchdarkly/overrides.json")) > > client, _ := ld.MakeCustomClient("YOUR_SDK_KEY", config, 5*time.Second) > ``` > > The Go SDK reads both JSON and YAML files. `ldoverrides.FileSource()` has the following options: > > * `FilePaths`: The files to read, in precedence order. At least one path is required. > * `DuplicateKeysHandling`: What to do when the same key appears in more than one file. `ldoverrides.DuplicateKeysFail`, the default, rejects the change. `ldoverrides.DuplicateKeysKeepFirst` uses the entry from the first file that defines the key. > * `ChangeDetection`: How the SDK detects file changes. Use `ldoverrides.Polling`, the default, or `ldoverrides.Watching`. > * `PollInterval`: The interval between checks in polling mode. The default and the minimum are one second. > > This example reads two files, uses the first entry for a key that appears in both, and watches the files for changes: > > ```go title="Go SDK v7.18+" lines wrap theme={null} > overrides := ldoverrides.FileSource(). > FilePaths("/etc/launchdarkly/overrides.json", "/etc/launchdarkly/team-overrides.json"). > DuplicateKeysHandling(ldoverrides.DuplicateKeysKeepFirst). > ChangeDetection(ldoverrides.Watching) > > config.DataSystem = ldcomponents.DataSystem().Default().Overrides(overrides) > ``` > > To check whether an override affected an evaluation: > > ```go title="Go SDK v7.18+" lines wrap theme={null} > _, detail, _ := client.BoolVariationDetail("my-boolean-flag-key", context, false) > if detail.Reason.IsOverrideAffected() { > fmt.Println("An override affected this evaluation") > } > ``` > > To learn more, read [`ldoverrides`](https://pkg.go.dev/github.com/launchdarkly/go-server-sdk/v7/ldoverrides). ### Node.js (server-side) > [accordion] Expand Node.js (server-side) code sample > > To use flag overrides, configure the data system with a file-based override source. > > > [!NOTE] > > > > **Supported versions** > > > > Flag overrides are available in the Node.js (server-side) SDK version 9.15 and later. > > This example reads overrides from `/etc/launchdarkly/overrides.json`: > > ```js title="Node.js (server-side) SDK v9.15+" lines wrap theme={null} > import { init } from '@launchdarkly/node-server-sdk'; > > const client = init('YOUR_SDK_KEY', { > dataSystem: { > overrides: { > type: 'file', > paths: ['/etc/launchdarkly/overrides.json'], > }, > }, > }); > ``` > > The SDK reads the override files when the client starts, without blocking `init`. Overrides that are in the files at startup are in effect after the promise that `waitForInitialization` returns settles, whether it resolves or rejects. An evaluation before then does not see those overrides. > > The `overrides` option has the following properties: > > * `type`: Always `'file'`. > * `paths`: The files to read, in precedence order. At least one path is required. > * `duplicateKeysHandling`: What to do when the same key appears in more than one file. `'fail'`, the default, rejects the change. `'ignore'` uses the entry from the first file that defines the key. > * `changeDetection`: How the SDK detects file changes. Use `'polling'`, the default, or `'watching'`. > * `pollInterval`: The interval between checks in polling mode, in seconds. The default and the minimum are one second. > * `yamlParser`: A function that parses YAML files. > > This example reads two files, uses the first entry for a key that appears in both, and watches the files for changes: > > ```js title="Node.js (server-side) SDK v9.15+" lines wrap theme={null} > const client = init('YOUR_SDK_KEY', { > dataSystem: { > overrides: { > type: 'file', > paths: ['/etc/launchdarkly/overrides.json', '/etc/launchdarkly/team-overrides.json'], > duplicateKeysHandling: 'ignore', > changeDetection: 'watching', > }, > }, > }); > ``` > > The Node.js (server-side) SDK reads JSON files. It does not include a YAML parser. To read files with a `.yaml` or `.yml` extension, supply a parser in `yamlParser` that returns the same structure as `JSON.parse`. If a configured file has a YAML extension and you do not supply a parser, creating the client fails. > > This example uses the `parse` function of the `yaml` package: > > ```js title="Node.js (server-side) SDK v9.15+" lines wrap theme={null} > import { init } from '@launchdarkly/node-server-sdk'; > import { parse } from 'yaml'; > > const client = init('YOUR_SDK_KEY', { > dataSystem: { > overrides: { > type: 'file', > paths: ['/etc/launchdarkly/overrides.yaml'], > yamlParser: parse, > }, > }, > }); > ``` > > To check whether an override affected an evaluation: > > ```js title="Node.js (server-side) SDK v9.15+" lines wrap theme={null} > const detail = await client.variationDetail('my-boolean-flag-key', context, false); > if (detail.reason.overrideAffected) { > console.log('An override affected this evaluation'); > } > ``` > > To learn more, read [`FileOverrideSourceOptions`](https://launchdarkly.github.io/js-core/packages/sdk/server-node/docs/interfaces/FileOverrideSourceOptions.html).